@rudderhq/server 0.3.6-canary.8 → 0.4.0

package/dist/services/chats.js

@@ -1,8 +1,8 @@
-import { approvals, assets, chatAttachments, chatContextLinks, chatConversations, chatConversationUserStates, chatMessages } from "@rudderhq/db";
-import { sanitizeChatStructuredPayload } from "@rudderhq/shared";
-import { and, desc, eq, gt, gte, inArray, isNull, sql } from "drizzle-orm";
+import { agentIntegrationChatBindings, agentIntegrations, approvals, assets, chatAttachments, chatContextLinks, chatConversations, chatConversationUserStates, chatGenerations, chatMessages, chatQueuedMessages, messengerCustomGroupEntries, messengerCustomGroups } from "@rudderhq/db";
+import { MESSENGER_FORK_GROUP_DEFAULT_ICON, sanitizeChatStructuredPayload } from "@rudderhq/shared";
+import { and, asc, desc, eq, gt, gte, inArray, isNull, lt, or, sql } from "drizzle-orm";
 import { randomUUID } from "node:crypto";
-import { notFound, unprocessable } from "../errors.js";
+import { conflict, notFound, unprocessable } from "../errors.js";
 import { logActivity } from "./activity-log.js";
 import { agentService } from "./agents.js";
 import { approvalService } from "./approvals.js";
@@ -10,8 +10,18 @@ import { issueApprovalService } from "./issue-approvals.js";
 import { issueService } from "./issues.js";
 import { normalizeLocalLibraryPathMarkdown } from "./library-path-markdown.js";
 import { organizationService } from "./orgs.js";
+function conversationMutability(row, sourceMetadata, sourceMetadataByConversationId) {
+    if (sourceMetadata)
+        return "external_bound_chat";
+    if ((row.forkedFromConversationId && sourceMetadataByConversationId.has(row.forkedFromConversationId)) ||
+        (row.forkRootConversationId && sourceMetadataByConversationId.has(row.forkRootConversationId))) {
+        return "native_fork_from_external";
+    }
+    return "native_chat";
+}
 import { buildSearchSnippet, CHAT_TRANSCRIPT_KEY, chatTranscriptFromPayload, chatTranscriptSummaryFromEntries, contentPath, escapeLikePattern, incomingMessagePreviewSql, issueProposalFromPayload, isVisibleIncomingChatMessage, listContextLinksForConversationIds, listPrimaryIssues, operationProposalDecisionStatusFromPayload, operationProposalFromPayload, resolveContextEntities, safeTrim, stripChatMetadataFromPayload, textContains, truncatePreview, visibleIncomingMessageSql, withOperationProposalDecisionState, withPersistedTranscript, } from "./chats.helpers.js";
 export function chatService(db) {
+    const QUEUED_MESSAGE_CLAIM_LEASE_MS = 2 * 60 * 1000;
     const issuesSvc = issueService(db);
     const approvalsSvc = approvalService(db);
     const issueApprovalsSvc = issueApprovalService(db);
@@ -51,7 +61,12 @@ export function chatService(db) {
         })
             .from(chatMessages)
             .innerJoin(chatConversationUserStates, and(eq(chatConversationUserStates.orgId, orgId), eq(chatConversationUserStates.userId, userId), eq(chatConversationUserStates.conversationId, chatMessages.conversationId)))
-            .where(and(eq(chatMessages.orgId, orgId), inArray(chatMessages.conversationId, conversationIds), isNull(chatMessages.supersededAt), visibleIncomingMessageSql(), gt(chatMessages.createdAt, chatConversationUserStates.lastReadAt)))
+            .where(and(eq(chatMessages.orgId, orgId), inArray(chatMessages.conversationId, conversationIds), isNull(chatMessages.supersededAt), visibleIncomingMessageSql(), gt(chatMessages.createdAt, chatConversationUserStates.lastReadAt), sql `not exists (
+            select 1
+            from ${agentIntegrationChatBindings}
+            where ${agentIntegrationChatBindings.orgId} = ${orgId}
+              and ${agentIntegrationChatBindings.conversationId} = ${chatMessages.conversationId}
+          )`))
             .groupBy(chatMessages.conversationId);
         return new Map(rows.map((row) => [row.conversationId, Number(row.count ?? 0)]));
     }
@@ -68,6 +83,35 @@ export function chatService(db) {
             .groupBy(chatMessages.conversationId);
         return new Set(rows.map((row) => row.conversationId));
     }
+    async function listConversationSourceMetadata(orgId, conversationIds) {
+        if (conversationIds.length === 0)
+            return new Map();
+        const rows = await db
+            .select({
+            conversationId: agentIntegrationChatBindings.conversationId,
+            integrationId: agentIntegrationChatBindings.integrationId,
+            provider: agentIntegrations.provider,
+            externalChatId: agentIntegrationChatBindings.externalChatId,
+            externalChatType: agentIntegrationChatBindings.externalChatType,
+        })
+            .from(agentIntegrationChatBindings)
+            .innerJoin(agentIntegrations, eq(agentIntegrations.id, agentIntegrationChatBindings.integrationId))
+            .where(and(eq(agentIntegrationChatBindings.orgId, orgId), inArray(agentIntegrationChatBindings.conversationId, conversationIds)))
+            .orderBy(agentIntegrationChatBindings.createdAt);
+        const map = new Map();
+        for (const row of rows) {
+            if (map.has(row.conversationId))
+                continue;
+            map.set(row.conversationId, {
+                source: "agent_integration",
+                provider: row.provider,
+                integrationId: row.integrationId,
+                externalChatId: row.externalChatId,
+                externalChatType: row.externalChatType,
+            });
+        }
+        return map;
+    }
     async function listLatestReplyPreviews(orgId, conversationIds) {
         if (conversationIds.length === 0)
             return new Map();
@@ -175,8 +219,14 @@ export function chatService(db) {
             await ensureConversationUserStates(rows, userId);
         }
         const conversationIds = rows.map((row) => row.id);
+        const sourceLookupConversationIds = [
+            ...new Set([
+                ...conversationIds,
+                ...rows.flatMap((row) => [row.forkedFromConversationId, row.forkRootConversationId].filter((id) => Boolean(id))),
+            ]),
+        ];
         const orgId = rows[0]?.orgId ?? null;
-        const [contextLinksByConversationId, primaryIssuesById, userStatesByConversationId, unreadCountsByConversationId, pendingProposalConversationIds, latestReplyPreviewsByConversationId, userMessageSummariesByConversationId,] = await Promise.all([
+        const [contextLinksByConversationId, primaryIssuesById, userStatesByConversationId, unreadCountsByConversationId, pendingProposalConversationIds, latestReplyPreviewsByConversationId, userMessageSummariesByConversationId, sourceMetadataByConversationId,] = await Promise.all([
             listContextLinksForConversationIds(db, rows.map((row) => row.id)),
             listPrimaryIssues(db, rows),
             userId && orgId
@@ -194,29 +244,45 @@ export function chatService(db) {
             orgId
                 ? listUserMessageSummaries(orgId, conversationIds)
                 : Promise.resolve(new Map()),
+            orgId
+                ? listConversationSourceMetadata(orgId, sourceLookupConversationIds)
+                : Promise.resolve(new Map()),
         ]);
-        return rows.map((row) => ({
-            ...row,
-            primaryIssue: row.primaryIssueId ? (primaryIssuesById.get(row.primaryIssueId) ?? null) : null,
-            latestReplyPreview: latestReplyPreviewsByConversationId.get(row.id) ?? null,
-            latestUserMessagePreview: userMessageSummariesByConversationId.get(row.id)?.latestPreview ?? null,
-            userMessageCount: userMessageSummariesByConversationId.get(row.id)?.count ?? 0,
-            contextLinks: contextLinksByConversationId.get(row.id) ?? [],
-            lastReadAt: userStatesByConversationId.get(row.id)?.lastReadAt ?? null,
-            isPinned: Boolean(userStatesByConversationId.get(row.id)?.pinnedAt),
-            unreadCount: unreadCountsByConversationId.get(row.id) ?? 0,
-            isUnread: (unreadCountsByConversationId.get(row.id) ?? 0) > 0,
-            needsAttention: (unreadCountsByConversationId.get(row.id) ?? 0) > 0 ||
-                pendingProposalConversationIds.has(row.id),
-        }));
+        return rows.map((row) => {
+            const sourceMetadata = sourceMetadataByConversationId.get(row.id) ?? null;
+            const isExternalBound = Boolean(sourceMetadata);
+            const unreadCount = isExternalBound ? 0 : (unreadCountsByConversationId.get(row.id) ?? 0);
+            return {
+                ...row,
+                primaryIssue: row.primaryIssueId ? (primaryIssuesById.get(row.primaryIssueId) ?? null) : null,
+                latestReplyPreview: latestReplyPreviewsByConversationId.get(row.id) ?? null,
+                latestUserMessagePreview: userMessageSummariesByConversationId.get(row.id)?.latestPreview ?? null,
+                userMessageCount: userMessageSummariesByConversationId.get(row.id)?.count ?? 0,
+                contextLinks: contextLinksByConversationId.get(row.id) ?? [],
+                sourceMetadata,
+                mutability: conversationMutability(row, sourceMetadata, sourceMetadataByConversationId),
+                lastReadAt: userStatesByConversationId.get(row.id)?.lastReadAt ?? null,
+                isPinned: Boolean(userStatesByConversationId.get(row.id)?.pinnedAt),
+                unreadCount,
+                isUnread: unreadCount > 0,
+                needsAttention: !isExternalBound && (unreadCount > 0 ||
+                    pendingProposalConversationIds.has(row.id)),
+            };
+        });
     }
     async function hydrateConversationSummaries(rows, userId) {
         if (userId) {
             await ensureConversationUserStates(rows, userId);
         }
         const conversationIds = rows.map((row) => row.id);
+        const sourceLookupConversationIds = [
+            ...new Set([
+                ...conversationIds,
+                ...rows.flatMap((row) => [row.forkedFromConversationId, row.forkRootConversationId].filter((id) => Boolean(id))),
+            ]),
+        ];
         const orgId = rows[0]?.orgId ?? null;
-        const [userStatesByConversationId, unreadCountsByConversationId, pendingProposalConversationIds, latestReplyPreviewsByConversationId, userMessageSummariesByConversationId,] = await Promise.all([
+        const [userStatesByConversationId, unreadCountsByConversationId, pendingProposalConversationIds, latestReplyPreviewsByConversationId, userMessageSummariesByConversationId, sourceMetadataByConversationId,] = await Promise.all([
             userId && orgId
                 ? listConversationUserStates(orgId, userId, conversationIds)
                 : Promise.resolve(new Map()),
@@ -232,19 +298,29 @@ export function chatService(db) {
             orgId
                 ? listUserMessageSummaries(orgId, conversationIds)
                 : Promise.resolve(new Map()),
+            orgId
+                ? listConversationSourceMetadata(orgId, sourceLookupConversationIds)
+                : Promise.resolve(new Map()),
         ]);
-        return rows.map((row) => ({
-            ...row,
-            latestReplyPreview: latestReplyPreviewsByConversationId.get(row.id) ?? null,
-            latestUserMessagePreview: userMessageSummariesByConversationId.get(row.id)?.latestPreview ?? null,
-            userMessageCount: userMessageSummariesByConversationId.get(row.id)?.count ?? 0,
-            lastReadAt: userStatesByConversationId.get(row.id)?.lastReadAt ?? null,
-            isPinned: Boolean(userStatesByConversationId.get(row.id)?.pinnedAt),
-            unreadCount: unreadCountsByConversationId.get(row.id) ?? 0,
-            isUnread: (unreadCountsByConversationId.get(row.id) ?? 0) > 0,
-            needsAttention: (unreadCountsByConversationId.get(row.id) ?? 0) > 0 ||
-                pendingProposalConversationIds.has(row.id),
-        }));
+        return rows.map((row) => {
+            const sourceMetadata = sourceMetadataByConversationId.get(row.id) ?? null;
+            const isExternalBound = Boolean(sourceMetadata);
+            const unreadCount = isExternalBound ? 0 : (unreadCountsByConversationId.get(row.id) ?? 0);
+            return {
+                ...row,
+                latestReplyPreview: latestReplyPreviewsByConversationId.get(row.id) ?? null,
+                latestUserMessagePreview: userMessageSummariesByConversationId.get(row.id)?.latestPreview ?? null,
+                userMessageCount: userMessageSummariesByConversationId.get(row.id)?.count ?? 0,
+                sourceMetadata,
+                mutability: conversationMutability(row, sourceMetadata, sourceMetadataByConversationId),
+                lastReadAt: userStatesByConversationId.get(row.id)?.lastReadAt ?? null,
+                isPinned: Boolean(userStatesByConversationId.get(row.id)?.pinnedAt),
+                unreadCount,
+                isUnread: unreadCount > 0,
+                needsAttention: !isExternalBound && (unreadCount > 0 ||
+                    pendingProposalConversationIds.has(row.id)),
+            };
+        });
     }
     async function getConversationOrThrow(id) {
         const row = await db
@@ -305,6 +381,328 @@ export function chatService(db) {
             .where(inArray(approvals.id, approvalIds));
         return new Map(approvalRows.map((row) => [row.id, row]));
     }
+    function isQueuePositionConflict(error) {
+        return Boolean(error
+            && typeof error === "object"
+            && "code" in error
+            && error.code === "23505");
+    }
+    function normalizeQueuedPayload(payload) {
+        return {
+            body: String(payload.body ?? ""),
+            attachmentIds: Array.isArray(payload.attachmentIds)
+                ? payload.attachmentIds.filter((id) => typeof id === "string")
+                : [],
+            projectId: typeof payload.projectId === "string" ? payload.projectId : null,
+            skillRefs: Array.isArray(payload.skillRefs)
+                ? payload.skillRefs.filter((ref) => typeof ref === "string")
+                : [],
+            accessMode: typeof payload.accessMode === "string" ? payload.accessMode : null,
+            model: typeof payload.model === "string" ? payload.model : null,
+            effort: typeof payload.effort === "string" ? payload.effort : null,
+            metadata: payload.metadata && typeof payload.metadata === "object" && !Array.isArray(payload.metadata)
+                ? payload.metadata
+                : null,
+        };
+    }
+    function hydrateQueuedMessage(row) {
+        return {
+            ...row,
+            payload: normalizeQueuedPayload(row.payload),
+        };
+    }
+    async function createGeneration(orgId, conversationId) {
+        const [row] = await db
+            .insert(chatGenerations)
+            .values({
+            orgId,
+            conversationId,
+            status: "active",
+        })
+            .returning();
+        if (!row)
+            throw new Error("Failed to create chat generation");
+        return row;
+    }
+    async function markGenerationTerminal(generationId, status) {
+        if (!generationId)
+            return null;
+        const now = new Date();
+        const [row] = await db
+            .update(chatGenerations)
+            .set({
+            status,
+            terminalReason: status,
+            completedAt: now,
+            updatedAt: now,
+        })
+            .where(eq(chatGenerations.id, generationId))
+            .returning();
+        return row ?? null;
+    }
+    async function getLatestActiveGeneration(conversationId) {
+        return db
+            .select()
+            .from(chatGenerations)
+            .where(and(eq(chatGenerations.conversationId, conversationId), inArray(chatGenerations.status, ["active", "tool_busy", "closing"])))
+            .orderBy(desc(chatGenerations.startedAt), desc(chatGenerations.createdAt))
+            .limit(1)
+            .then((rows) => rows[0] ?? null);
+    }
+    async function getLatestGeneration(conversationId) {
+        return db
+            .select()
+            .from(chatGenerations)
+            .where(eq(chatGenerations.conversationId, conversationId))
+            .orderBy(desc(chatGenerations.startedAt), desc(chatGenerations.createdAt))
+            .limit(1)
+            .then((rows) => rows[0] ?? null);
+    }
+    async function listQueuedMessages(conversationId) {
+        await reclaimStaleQueuedMessageClaims(conversationId);
+        const rows = await db
+            .select()
+            .from(chatQueuedMessages)
+            .where(and(eq(chatQueuedMessages.conversationId, conversationId), inArray(chatQueuedMessages.status, ["queued", "steer_pending", "dequeue_claimed", "running"])))
+            .orderBy(asc(chatQueuedMessages.position), asc(chatQueuedMessages.createdAt));
+        return rows.map(hydrateQueuedMessage);
+    }
+    async function getQueueSnapshot(conversationId, activeGenerationId) {
+        const activeGeneration = activeGenerationId
+            ? { id: activeGenerationId }
+            : await getLatestActiveGeneration(conversationId);
+        return {
+            activeGenerationId: activeGeneration?.id ?? null,
+            items: await listQueuedMessages(conversationId),
+        };
+    }
+    async function createQueuedMessage(input) {
+        const payload = {
+            ...input.payload,
+            body: input.payload.body.trim(),
+            attachmentIds: input.payload.attachmentIds ?? [],
+            skillRefs: input.payload.skillRefs ?? [],
+            projectId: input.payload.projectId ?? null,
+            accessMode: input.payload.accessMode ?? null,
+            model: input.payload.model ?? null,
+            effort: input.payload.effort ?? null,
+            metadata: input.payload.metadata ?? null,
+        };
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            try {
+                return await db.transaction(async (tx) => {
+                    const existing = await tx
+                        .select()
+                        .from(chatQueuedMessages)
+                        .where(and(eq(chatQueuedMessages.conversationId, input.conversationId), eq(chatQueuedMessages.clientMutationId, input.clientMutationId)))
+                        .limit(1)
+                        .then((rows) => rows[0] ?? null);
+                    if (existing) {
+                        if (JSON.stringify(existing.payload) !== JSON.stringify(payload)) {
+                            throw conflict("Queued message idempotency key reused with a different payload");
+                        }
+                        return hydrateQueuedMessage(existing);
+                    }
+                    const [positionRow] = await tx
+                        .select({
+                        nextPosition: sql `coalesce(max(${chatQueuedMessages.position}), 0) + 1`,
+                    })
+                        .from(chatQueuedMessages)
+                        .where(eq(chatQueuedMessages.conversationId, input.conversationId));
+                    const [row] = await tx
+                        .insert(chatQueuedMessages)
+                        .values({
+                        orgId: input.orgId,
+                        conversationId: input.conversationId,
+                        clientMutationId: input.clientMutationId,
+                        position: Number(positionRow?.nextPosition ?? 1),
+                        payload,
+                        expectedGenerationId: input.expectedGenerationId ?? null,
+                    })
+                        .returning();
+                    if (!row)
+                        throw new Error("Failed to create queued chat message");
+                    return hydrateQueuedMessage(row);
+                });
+            }
+            catch (error) {
+                if (attempt < 2 && isQueuePositionConflict(error))
+                    continue;
+                throw error;
+            }
+        }
+        throw new Error("Failed to create queued chat message");
+    }
+    async function updateQueuedMessage(input) {
+        const now = new Date();
+        const [row] = await db
+            .update(chatQueuedMessages)
+            .set({
+            payload: {
+                ...input.payload,
+                body: input.payload.body.trim(),
+                attachmentIds: input.payload.attachmentIds ?? [],
+                skillRefs: input.payload.skillRefs ?? [],
+                projectId: input.payload.projectId ?? null,
+                accessMode: input.payload.accessMode ?? null,
+                model: input.payload.model ?? null,
+                effort: input.payload.effort ?? null,
+                metadata: input.payload.metadata ?? null,
+            },
+            version: input.version + 1,
+            lastDeliveryReason: null,
+            updatedAt: now,
+        })
+            .where(and(eq(chatQueuedMessages.conversationId, input.conversationId), eq(chatQueuedMessages.id, input.itemId), eq(chatQueuedMessages.version, input.version), eq(chatQueuedMessages.status, "queued")))
+            .returning();
+        if (!row)
+            throw conflict("Queued message was changed or is no longer editable");
+        return hydrateQueuedMessage(row);
+    }
+    async function cancelQueuedMessage(input) {
+        const now = new Date();
+        const conditions = [
+            eq(chatQueuedMessages.conversationId, input.conversationId),
+            eq(chatQueuedMessages.id, input.itemId),
+            eq(chatQueuedMessages.status, "queued"),
+        ];
+        if (input.version)
+            conditions.push(eq(chatQueuedMessages.version, input.version));
+        const [row] = await db
+            .update(chatQueuedMessages)
+            .set({
+            status: "cancelled",
+            version: sql `${chatQueuedMessages.version} + 1`,
+            cancelledAt: now,
+            updatedAt: now,
+        })
+            .where(and(...conditions))
+            .returning();
+        if (!row)
+            throw conflict("Queued message was changed or is no longer cancellable");
+        return hydrateQueuedMessage(row);
+    }
+    async function markQueuedMessageSteerFallback(input) {
+        const now = new Date();
+        const [row] = await db
+            .update(chatQueuedMessages)
+            .set({
+            status: "queued",
+            activeGenerationId: input.activeGenerationId ?? null,
+            deliveryAttempts: sql `${chatQueuedMessages.deliveryAttempts} + 1`,
+            lastAttemptAt: now,
+            lastDeliveryReason: input.reason,
+            version: sql `${chatQueuedMessages.version} + 1`,
+            updatedAt: now,
+        })
+            .where(and(eq(chatQueuedMessages.conversationId, input.conversationId), eq(chatQueuedMessages.id, input.itemId), eq(chatQueuedMessages.status, "queued")))
+            .returning();
+        if (!row)
+            throw conflict("Queued message was changed or is no longer steerable");
+        return hydrateQueuedMessage(row);
+    }
+    async function claimNextQueuedMessage(conversationId) {
+        await reclaimStaleQueuedMessageClaims(conversationId);
+        const now = new Date();
+        return db.transaction(async (tx) => {
+            const [candidate] = await tx
+                .select()
+                .from(chatQueuedMessages)
+                .where(and(eq(chatQueuedMessages.conversationId, conversationId), eq(chatQueuedMessages.status, "queued")))
+                .orderBy(asc(chatQueuedMessages.position), asc(chatQueuedMessages.createdAt))
+                .limit(1);
+            if (!candidate)
+                return null;
+            const [row] = await tx
+                .update(chatQueuedMessages)
+                .set({
+                status: "dequeue_claimed",
+                dequeuedAt: now,
+                deliveryAttempts: sql `${chatQueuedMessages.deliveryAttempts} + 1`,
+                lastAttemptAt: now,
+                lastDeliveryReason: null,
+                version: sql `${chatQueuedMessages.version} + 1`,
+                updatedAt: now,
+            })
+                .where(and(eq(chatQueuedMessages.id, candidate.id), eq(chatQueuedMessages.conversationId, conversationId), eq(chatQueuedMessages.status, "queued"), eq(chatQueuedMessages.version, candidate.version)))
+                .returning();
+            return row ? hydrateQueuedMessage(row) : null;
+        });
+    }
+    async function releaseQueuedMessageClaim(input) {
+        const now = new Date();
+        const [row] = await db
+            .update(chatQueuedMessages)
+            .set({
+            status: "queued",
+            lastDeliveryReason: input.reason,
+            version: sql `${chatQueuedMessages.version} + 1`,
+            updatedAt: now,
+        })
+            .where(and(eq(chatQueuedMessages.conversationId, input.conversationId), eq(chatQueuedMessages.id, input.itemId), eq(chatQueuedMessages.status, "dequeue_claimed")))
+            .returning();
+        return row ? hydrateQueuedMessage(row) : null;
+    }
+    async function reclaimStaleQueuedMessageClaims(conversationId) {
+        const cutoff = new Date(Date.now() - QUEUED_MESSAGE_CLAIM_LEASE_MS);
+        await db
+            .update(chatQueuedMessages)
+            .set({
+            status: "queued",
+            lastDeliveryReason: "claim_expired",
+            version: sql `${chatQueuedMessages.version} + 1`,
+            updatedAt: new Date(),
+        })
+            .where(and(eq(chatQueuedMessages.conversationId, conversationId), eq(chatQueuedMessages.status, "dequeue_claimed"), lt(chatQueuedMessages.updatedAt, cutoff)));
+    }
+    async function assertQueuedMessageClaimedForDelivery(input) {
+        const row = await db
+            .select()
+            .from(chatQueuedMessages)
+            .where(and(eq(chatQueuedMessages.conversationId, input.conversationId), eq(chatQueuedMessages.id, input.itemId)))
+            .limit(1)
+            .then((rows) => rows[0] ?? null);
+        if (!row || row.status !== "dequeue_claimed") {
+            throw conflict("Queued message is not claimed for delivery");
+        }
+        const payload = normalizeQueuedPayload(row.payload);
+        if (payload.body.trim() !== input.body.trim()) {
+            throw conflict("Queued message body no longer matches claimed payload");
+        }
+        return hydrateQueuedMessage(row);
+    }
+    async function markQueuedMessageRunning(input) {
+        const now = new Date();
+        const [row] = await db
+            .update(chatQueuedMessages)
+            .set({
+            status: "running",
+            sourceMessageId: input.sourceMessageId,
+            deliveredMessageId: input.sourceMessageId,
+            version: sql `${chatQueuedMessages.version} + 1`,
+            updatedAt: now,
+        })
+            .where(and(eq(chatQueuedMessages.conversationId, input.conversationId), eq(chatQueuedMessages.id, input.itemId), eq(chatQueuedMessages.status, "dequeue_claimed")))
+            .returning();
+        if (!row)
+            throw conflict("Queued message is no longer deliverable");
+        return hydrateQueuedMessage(row);
+    }
+    async function markQueuedMessageDeliveryTerminal(input) {
+        const now = new Date();
+        const nextStatus = input.status === "completed" ? "completed" : "failed";
+        const [row] = await db
+            .update(chatQueuedMessages)
+            .set({
+            status: nextStatus,
+            lastDeliveryReason: input.status === "completed" ? null : input.status,
+            version: sql `${chatQueuedMessages.version} + 1`,
+            updatedAt: now,
+        })
+            .where(and(eq(chatQueuedMessages.conversationId, input.conversationId), eq(chatQueuedMessages.id, input.itemId), inArray(chatQueuedMessages.status, ["dequeue_claimed", "running"])))
+            .returning();
+        return row ? hydrateQueuedMessage(row) : null;
+    }
     async function hydrateMessages(rows, options = {}) {
         const includeTranscript = options.includeTranscript !== false;
         const [attachmentsByMessageId, approvalsById] = await Promise.all([
@@ -493,6 +891,208 @@ export function chatService(db) {
         });
         return getById(created.id);
     }
+    function forkSystemEventBody(sourceConversation, sourceMessageId) {
+        const messageSuffix = sourceMessageId ? ` at message ${sourceMessageId}` : "";
+        return `Forked from [${sourceConversation.title}](chat://${sourceConversation.id})${messageSuffix}.`;
+    }
+    async function findForkFamilyGroup(client, orgId, userId, rootConversationId) {
+        const rootThreadKey = `chat:${rootConversationId}`;
+        return client
+            .select({ id: messengerCustomGroups.id })
+            .from(messengerCustomGroups)
+            .innerJoin(messengerCustomGroupEntries, eq(messengerCustomGroupEntries.groupId, messengerCustomGroups.id))
+            .where(and(eq(messengerCustomGroups.orgId, orgId), eq(messengerCustomGroups.userId, userId), eq(messengerCustomGroupEntries.orgId, orgId), eq(messengerCustomGroupEntries.userId, userId), eq(messengerCustomGroupEntries.threadKey, rootThreadKey)))
+            .orderBy(asc(messengerCustomGroups.sortOrder), asc(messengerCustomGroups.createdAt))
+            .limit(1)
+            .then((rows) => rows[0] ?? null);
+    }
+    async function createForkFamilyGroup(client, orgId, userId, name) {
+        const [lastGroup] = await client
+            .select({ sortOrder: messengerCustomGroups.sortOrder })
+            .from(messengerCustomGroups)
+            .where(and(eq(messengerCustomGroups.orgId, orgId), eq(messengerCustomGroups.userId, userId)))
+            .orderBy(desc(messengerCustomGroups.sortOrder))
+            .limit(1);
+        const now = new Date();
+        const [group] = await client
+            .insert(messengerCustomGroups)
+            .values({
+            orgId,
+            userId,
+            name: name.trim() || "Forked conversation",
+            icon: MESSENGER_FORK_GROUP_DEFAULT_ICON,
+            sortOrder: (lastGroup?.sortOrder ?? -1) + 1,
+            updatedAt: now,
+        })
+            .returning();
+        if (!group)
+            throw new Error("Failed to create Messenger fork group");
+        return group;
+    }
+    async function assignForkThreadToGroup(client, orgId, userId, groupId, threadKey) {
+        const [lastEntry] = await client
+            .select({ sortOrder: messengerCustomGroupEntries.sortOrder })
+            .from(messengerCustomGroupEntries)
+            .where(and(eq(messengerCustomGroupEntries.orgId, orgId), eq(messengerCustomGroupEntries.userId, userId), eq(messengerCustomGroupEntries.groupId, groupId)))
+            .orderBy(desc(messengerCustomGroupEntries.sortOrder))
+            .limit(1);
+        const now = new Date();
+        await client
+            .insert(messengerCustomGroupEntries)
+            .values({
+            orgId,
+            userId,
+            groupId,
+            threadKey,
+            sortOrder: (lastEntry?.sortOrder ?? -1) + 1,
+            updatedAt: now,
+        })
+            .onConflictDoNothing();
+    }
+    async function ensureForkFamilyGroup(client, orgId, userId, rootConversationId, sourceConversationId, childConversationId, groupName) {
+        const existing = await findForkFamilyGroup(client, orgId, userId, rootConversationId);
+        const group = existing ?? await createForkFamilyGroup(client, orgId, userId, groupName);
+        for (const threadKey of [
+            `chat:${rootConversationId}`,
+            `chat:${sourceConversationId}`,
+            `chat:${childConversationId}`,
+        ]) {
+            await assignForkThreadToGroup(client, orgId, userId, group.id, threadKey);
+        }
+    }
+    async function forkConversation(input) {
+        const created = await db.transaction(async (tx) => {
+            const source = await tx
+                .select()
+                .from(chatConversations)
+                .where(and(eq(chatConversations.id, input.sourceConversationId), eq(chatConversations.orgId, input.orgId)))
+                .then((rows) => rows[0] ?? null);
+            if (!source)
+                throw notFound("Chat conversation not found");
+            const rootConversationId = source.forkRootConversationId ?? source.id;
+            const messageConditions = [
+                eq(chatMessages.conversationId, source.id),
+                eq(chatMessages.orgId, input.orgId),
+                isNull(chatMessages.supersededAt),
+            ];
+            let forkSourceCreatedAt = null;
+            if (input.sourceMessageId) {
+                const sourceMessage = await tx
+                    .select({
+                    id: chatMessages.id,
+                    kind: chatMessages.kind,
+                    role: chatMessages.role,
+                    createdAt: chatMessages.createdAt,
+                })
+                    .from(chatMessages)
+                    .where(and(...messageConditions, eq(chatMessages.id, input.sourceMessageId)))
+                    .then((rows) => rows[0] ?? null);
+                if (!sourceMessage)
+                    throw unprocessable("Fork source message must belong to the source conversation");
+                if (sourceMessage.role !== "assistant" || sourceMessage.kind !== "message") {
+                    throw unprocessable("Fork source message must be an assistant response");
+                }
+                forkSourceCreatedAt = sourceMessage.createdAt;
+            }
+            const now = new Date();
+            const [child] = await tx
+                .insert(chatConversations)
+                .values({
+                orgId: input.orgId,
+                status: "active",
+                title: input.title?.trim() || source.title,
+                summary: source.summary,
+                preferredAgentId: source.preferredAgentId,
+                routedAgentId: source.routedAgentId,
+                primaryIssueId: source.primaryIssueId,
+                forkedFromConversationId: source.id,
+                forkedFromMessageId: input.sourceMessageId ?? null,
+                forkRootConversationId: rootConversationId,
+                issueCreationMode: source.issueCreationMode,
+                planMode: source.planMode,
+                createdByUserId: input.createdByUserId,
+                createdAt: now,
+                updatedAt: now,
+            })
+                .returning();
+            if (!child)
+                throw new Error("Failed to create forked chat conversation");
+            const contextLinks = await tx
+                .select()
+                .from(chatContextLinks)
+                .where(eq(chatContextLinks.conversationId, source.id))
+                .orderBy(chatContextLinks.createdAt);
+            if (contextLinks.length > 0) {
+                await tx
+                    .insert(chatContextLinks)
+                    .values(contextLinks.map((link) => ({
+                    orgId: input.orgId,
+                    conversationId: child.id,
+                    entityType: link.entityType,
+                    entityId: link.entityId,
+                    metadata: link.metadata,
+                })))
+                    .onConflictDoNothing();
+            }
+            const messagesToCopy = await tx
+                .select()
+                .from(chatMessages)
+                .where(and(...messageConditions, ...(forkSourceCreatedAt && input.sourceMessageId
+                ? [or(lt(chatMessages.createdAt, forkSourceCreatedAt), eq(chatMessages.id, input.sourceMessageId))]
+                : [])))
+                .orderBy(chatMessages.createdAt, chatMessages.id);
+            const forkMessages = input.sourceMessageId
+                ? messagesToCopy.slice(0, messagesToCopy.findIndex((message) => message.id === input.sourceMessageId) + 1)
+                : messagesToCopy;
+            if (forkMessages.length > 0) {
+                await tx.insert(chatMessages).values(forkMessages.map((message) => ({
+                    orgId: input.orgId,
+                    conversationId: child.id,
+                    role: message.role,
+                    kind: message.kind,
+                    status: message.status === "streaming" ? "interrupted" : message.status,
+                    body: message.body,
+                    structuredPayload: null,
+                    approvalId: null,
+                    runId: null,
+                    replyingAgentId: message.replyingAgentId,
+                    chatTurnId: null,
+                    turnVariant: 0,
+                    createdAt: message.createdAt,
+                    updatedAt: message.updatedAt,
+                })));
+            }
+            const [systemEvent] = await tx
+                .insert(chatMessages)
+                .values({
+                orgId: input.orgId,
+                conversationId: child.id,
+                role: "system",
+                kind: "system_event",
+                status: "completed",
+                body: forkSystemEventBody(source, input.sourceMessageId ?? null),
+                structuredPayload: {
+                    type: "chat_fork",
+                    sourceConversationId: source.id,
+                    sourceMessageId: input.sourceMessageId ?? null,
+                    forkRootConversationId: rootConversationId,
+                },
+                createdAt: now,
+                updatedAt: now,
+            })
+                .returning();
+            await tx
+                .update(chatConversations)
+                .set({
+                lastMessageAt: systemEvent?.createdAt ?? now,
+                updatedAt: now,
+            })
+                .where(eq(chatConversations.id, child.id));
+            await ensureForkFamilyGroup(tx, input.orgId, input.userId, rootConversationId, source.id, child.id, source.title);
+            return child;
+        });
+        return getById(created.id, input.userId);
+    }
     async function update(id, patch) {
         const [updated] = await db
             .update(chatConversations)
@@ -506,14 +1106,14 @@ export function chatService(db) {
             return null;
         return getById(id);
     }
-    async function updateDefaultTitle(id, title) {
+    async function updateDefaultTitle(id, title, expectedCurrentTitle = "New chat") {
         const [updated] = await db
             .update(chatConversations)
             .set({
             title,
             updatedAt: new Date(),
         })
-            .where(and(eq(chatConversations.id, id), eq(chatConversations.title, "New chat")))
+            .where(and(eq(chatConversations.id, id), eq(chatConversations.title, expectedCurrentTitle)))
             .returning();
         if (!updated)
             return null;
@@ -1462,10 +2062,26 @@ export function chatService(db) {
         replaceSystemGeneratedTitle,
         listAttachmentsForConversation,
         remove,
+        forkConversation,
         resolve,
         markRead,
         markUnread,
         setPinned,
+        createGeneration,
+        markGenerationTerminal,
+        getLatestActiveGeneration,
+        getLatestGeneration,
+        getQueueSnapshot,
+        listQueuedMessages,
+        createQueuedMessage,
+        updateQueuedMessage,
+        cancelQueuedMessage,
+        markQueuedMessageSteerFallback,
+        claimNextQueuedMessage,
+        releaseQueuedMessageClaim,
+        assertQueuedMessageClaimedForDelivery,
+        markQueuedMessageRunning,
+        markQueuedMessageDeliveryTerminal,
         listMessages,
         getMessageTranscript,
         addMessage,