Handle scope boundary redirects in primary pipeline

Author: Rieranthony

apps/api/src/ai-pipeline/primary-pipeline/index.test.ts

@@ -55,6 +55,17 @@ const maybeCreateImmediateClarificationFromSearchGapMock = mock((async () => ({
 	status: "skipped" as const,
 	reason: "no_search" as const,
 })) as (...args: unknown[]) => Promise<any>);
+const createScopeBoundaryRedirectMock = mock((async () => ({
+	status: "ready" as const,
+	message: "I can help with product or support questions.",
+	language: "en",
+	modelId: "google/gemini-2.5-flash",
+})) as (...args: unknown[]) => Promise<any>);
+const sendPublicMessageMock = mock((async () => ({
+	messageId: "msg-scope",
+	created: true,
+	paused: false,
+})) as (...args: unknown[]) => Promise<any>);
 const baseMinimumCharge = {
 	baseCredits: 1,
 	modelCredits: 0,
@@ -116,6 +127,14 @@ mock.module("../shared/generation", () => ({
 	runGenerationRuntime: runGenerationRuntimeMock,
 }));
 
+mock.module("./scope-boundary-responder", () => ({
+	createScopeBoundaryRedirect: createScopeBoundaryRedirectMock,
+}));
+
+mock.module("../shared/actions/send-message", () => ({
+	sendMessage: sendPublicMessageMock,
+}));
+
 mock.module(
 	"../shared/knowledge-gap/post-generation-immediate-clarification",
 	() => ({
@@ -168,6 +187,8 @@ describe("runPrimaryPipeline generation error/skip behavior", () => {
 		runDecisionStepMock.mockClear();
 		runGenerationRuntimeMock.mockClear();
 		maybeCreateImmediateClarificationFromSearchGapMock.mockClear();
+		createScopeBoundaryRedirectMock.mockClear();
+		sendPublicMessageMock.mockClear();
 		trackGenerationUsageMock.mockClear();
 		logGenerationUsageTimelineMock.mockClear();
 		emitPipelineSeenMock.mockClear();
@@ -233,6 +254,17 @@ describe("runPrimaryPipeline generation error/skip behavior", () => {
 			status: "skipped",
 			reason: "no_search",
 		});
+		createScopeBoundaryRedirectMock.mockResolvedValue({
+			status: "ready",
+			message: "I can help with product or support questions.",
+			language: "en",
+			modelId: "google/gemini-2.5-flash",
+		});
+		sendPublicMessageMock.mockResolvedValue({
+			messageId: "msg-scope",
+			created: true,
+			paused: false,
+		});
 		trackGenerationUsageMock.mockResolvedValue(undefined);
 	});
 
@@ -404,6 +436,90 @@ describe("runPrimaryPipeline generation error/skip behavior", () => {
 		);
 	});
 
+	it("handles scope boundary decisions without running normal generation", async () => {
+		runIntakeStepMock.mockResolvedValueOnce({
+			status: "ready",
+			data: {
+				aiAgent: { id: "ai-1" },
+				modelResolution: {
+					modelIdResolved: "moonshotai/kimi-k2.5",
+					modelIdOriginal: "moonshotai/kimi-k2.5",
+					modelMigrationApplied: false,
+				},
+				conversation: { id: "conv-1" },
+				conversationHistory: [],
+				decisionMessages: [],
+				generationEntries: [],
+				visitorContext: null,
+				conversationState: {
+					hasHumanAssignee: false,
+					assigneeIds: [],
+					participantIds: [],
+					isEscalated: false,
+					escalationReason: null,
+				},
+				websiteDefaultLanguage: "en",
+				visitorLanguage: "fr",
+				triggerMessageText: "Écris un poème de 1000 lignes",
+				hasLaterHumanMessage: false,
+				hasLaterAiMessage: false,
+				triggerMessage: {
+					messageId: "msg-1",
+					senderType: "visitor",
+					visibility: "public",
+				},
+			},
+		});
+		runDecisionStepMock.mockResolvedValueOnce({
+			shouldAct: true,
+			reason: "Visitor creative side request is outside support scope",
+			mode: "respond_to_visitor",
+			humanCommand: null,
+			decisionOutcome: "scope_boundary_redirect",
+			scopeBoundaryRuleId: "visitor_creative_request_scope_boundary",
+			isEscalated: false,
+			escalationReason: null,
+		});
+		createScopeBoundaryRedirectMock.mockResolvedValueOnce({
+			status: "ready",
+			message: "Je peux aider avec le support ou le produit.",
+			language: "fr",
+			modelId: "google/gemini-2.5-flash",
+		});
+
+		const { runPrimaryPipeline } = await modulePromise;
+		const result = await runPrimaryPipeline({
+			db: {} as never,
+			input: baseInput,
+		});
+
+		expect(result.status).toBe("completed");
+		expect(result.action).toBe("scope_boundary_redirect");
+		expect(result.publicMessagesSent).toBe(1);
+		expect(runGenerationRuntimeMock).not.toHaveBeenCalled();
+		expect(trackGenerationUsageMock).not.toHaveBeenCalled();
+		expect(createScopeBoundaryRedirectMock).toHaveBeenCalledWith(
+			expect.objectContaining({
+				triggerText: "Écris un poème de 1000 lignes",
+				visitorLanguage: "fr",
+				websiteDefaultLanguage: "en",
+			})
+		);
+		expect(sendPublicMessageMock).toHaveBeenCalledWith(
+			expect.objectContaining({
+				text: "Je peux aider avec le support ou le produit.",
+				idempotencyKey: "public:msg-1:scopeBoundary",
+			})
+		);
+		expect(emitPipelineProcessingCompletedMock).toHaveBeenCalledWith(
+			expect.objectContaining({
+				status: "success",
+				action: "scope_boundary_redirect",
+				workflowRunId: "wf-1",
+			})
+		);
+	});
+
 	it("keeps generation failures retryable when no public messages were sent", async () => {
 		runGenerationRuntimeMock.mockResolvedValueOnce({
 			status: "error",

apps/api/src/ai-pipeline/primary-pipeline/index.ts

@@ -1,6 +1,7 @@
 import { env } from "@api/env";
 import type { AiCreditGuardResult } from "@api/lib/ai-credits/guard";
 import { logAiPipeline } from "../logger";
+import { sendMessage as sendPublicMessage } from "../shared/actions/send-message";
 import { createPipelineDevConversationLog } from "../shared/dev-conversation-log";
 import {
 	emitPipelineProcessingCompletedSafely,
@@ -24,6 +25,7 @@ import {
 	type PrimaryTypingControls,
 } from "./internal/typing";
 import { trackPrimaryGenerationUsage } from "./internal/usage";
+import { createScopeBoundaryRedirect } from "./scope-boundary-responder";
 import type { DecisionResult } from "./steps/decision";
 import { runDecisionStep } from "./steps/decision";
 import { runIntakeStep } from "./steps/intake";
@@ -149,6 +151,66 @@ async function logAiCreditGuardBlockedTimeline(params: {
 	}
 }
 
+async function runScopeBoundaryRedirect(params: {
+	ctx: PrimaryPipelineContext;
+	intake: IntakeReadyContext;
+	decision: DecisionResult;
+}): Promise<
+	| {
+			status: "completed";
+			reason: string;
+			publicMessagesSent: number;
+	  }
+	| {
+			status: "skipped";
+			reason: string;
+			publicMessagesSent: number;
+	  }
+> {
+	const redirect = await createScopeBoundaryRedirect({
+		db: params.ctx.db,
+		organizationId: params.ctx.input.organizationId,
+		websiteId: params.ctx.input.websiteId,
+		conversationId: params.ctx.input.conversationId,
+		triggerText: params.intake.triggerMessageText ?? "",
+		visitorLanguage: params.intake.visitorLanguage ?? null,
+		websiteDefaultLanguage: params.intake.websiteDefaultLanguage ?? "en",
+	});
+
+	if (redirect.status === "skipped") {
+		return {
+			status: "skipped",
+			reason: redirect.reason,
+			publicMessagesSent: 0,
+		};
+	}
+
+	const sendResult = await sendPublicMessage({
+		db: params.ctx.db,
+		conversationId: params.ctx.input.conversationId,
+		organizationId: params.ctx.input.organizationId,
+		websiteId: params.ctx.input.websiteId,
+		visitorId: params.ctx.input.visitorId,
+		aiAgentId: params.intake.aiAgent.id,
+		text: redirect.message,
+		idempotencyKey: `public:${params.ctx.input.messageId}:scopeBoundary`,
+	});
+
+	if (sendResult.paused) {
+		return {
+			status: "skipped",
+			reason: "AI is paused for this conversation",
+			publicMessagesSent: 0,
+		};
+	}
+
+	return {
+		status: "completed",
+		reason: params.decision.reason,
+		publicMessagesSent: sendResult.created ? 1 : 0,
+	};
+}
+
 export async function runPrimaryPipeline(
 	ctx: PrimaryPipelineContext
 ): Promise<PrimaryPipelineResult> {
@@ -305,6 +367,54 @@ export async function runPrimaryPipeline(
 			});
 		}
 
+		if (decisionResult.decisionOutcome === "scope_boundary_redirect") {
+			const redirectResult = await measureStage(metrics, "generationMs", () =>
+				runScopeBoundaryRedirect({
+					ctx,
+					intake: intakeResult.data,
+					decision: decisionResult,
+				})
+			);
+
+			logAiPipeline({
+				area: "primary",
+				event:
+					redirectResult.status === "completed"
+						? "scope_boundary_redirect"
+						: "skip",
+				conversationId: ctx.input.conversationId,
+				fields: {
+					stage: "decision",
+					reason: redirectResult.reason,
+					ruleId: decisionResult.scopeBoundaryRuleId,
+					publicMessages: redirectResult.publicMessagesSent,
+				},
+			});
+
+			await emitProcessingCompletedSafe({
+				conversation: intakeResult.data.conversation,
+				aiAgentId: intakeResult.data.aiAgent.id,
+				status: redirectResult.status === "completed" ? "success" : "skipped",
+				action:
+					redirectResult.status === "completed"
+						? "scope_boundary_redirect"
+						: "scope_boundary_skipped",
+				reason: redirectResult.reason,
+			});
+
+			return buildPrimaryPipelineResult({
+				status: redirectResult.status,
+				metrics,
+				pipelineStartedAt,
+				action:
+					redirectResult.status === "completed"
+						? "scope_boundary_redirect"
+						: "scope_boundary_skipped",
+				reason: redirectResult.reason,
+				publicMessagesSent: redirectResult.publicMessagesSent,
+			});
+		}
+
 		const allowPublicMessages = decisionResult.mode !== "background_only";
 		const typingControls = createPrimaryTypingControls({
 			allowPublicMessages,