Merge pull request #66 from MaxLinCode/claude/pass-clarification-slots-to-llm

Pass clarificationSlots to LLM conversation responder

Author: MaxLinCode

apps/web/src/app/api/telegram/webhook/route.test.ts

@@ -156,6 +156,7 @@ function buildRoutedTurn(input: {
   ambiguity?: "none" | "low" | "high";
   resolvedProposalId?: string;
   committedSlots?: Record<string, string | number | TimeSpec>;
+  clarificationSlots?: string[];
 }): RoutedTurn {
   return {
     interpretation: {
@@ -186,6 +187,9 @@ function buildRoutedTurn(input: {
           ? { mutationInputSource: "direct_user_turn" as const }
           : {}),
       committedSlots: input.committedSlots ?? {},
+      ...(input.clarificationSlots
+        ? { clarificationSlots: input.clarificationSlots }
+        : {}),
     },
   };
 }
@@ -923,6 +927,84 @@ describe("telegram webhook route", () => {
     expect(listTasksForTests()).toHaveLength(0);
   });
 
+  it("passes clarificationSlots to the conversation responder when the turn router returns ask_clarification", async () => {
+    process.env.TELEGRAM_WEBHOOK_SECRET = "test-webhook-secret";
+    const conversationResponder = vi.fn(async () => ({
+      reply: "When would you like me to schedule that?",
+    }));
+
+    const response = await handleTelegramWebhook(
+      buildRequest({
+        update_id: 300,
+        message: {
+          message_id: 200,
+          date: 1_700_000_000,
+          text: "Schedule an oil change",
+          chat: { id: 999, type: "private" },
+          from: { id: 123, is_bot: false, first_name: "Max" },
+        },
+      }),
+      {
+        store: getDefaultInboxProcessingStore(),
+        calendar: getDefaultCalendarAdapter(),
+        primeProcessingStore: seedInboxItemForProcessingTests,
+        conversationResponder,
+        turnRouter: async () =>
+          buildRoutedTurn({
+            turnType: "planning_request",
+            action: "ask_clarification",
+            clarificationSlots: ["time"],
+          }),
+      },
+    );
+
+    expect(response.status).toBe(200);
+    expect(conversationResponder).toHaveBeenCalledWith(
+      expect.objectContaining({
+        clarificationSlots: ["time"],
+      }),
+    );
+  });
+
+  it("passes multiple clarificationSlots to the conversation responder", async () => {
+    process.env.TELEGRAM_WEBHOOK_SECRET = "test-webhook-secret";
+    const conversationResponder = vi.fn(async () => ({
+      reply: "What would you like to schedule, and what time?",
+    }));
+
+    const response = await handleTelegramWebhook(
+      buildRequest({
+        update_id: 301,
+        message: {
+          message_id: 201,
+          date: 1_700_000_000,
+          text: "Schedule something",
+          chat: { id: 999, type: "private" },
+          from: { id: 123, is_bot: false, first_name: "Max" },
+        },
+      }),
+      {
+        store: getDefaultInboxProcessingStore(),
+        calendar: getDefaultCalendarAdapter(),
+        primeProcessingStore: seedInboxItemForProcessingTests,
+        conversationResponder,
+        turnRouter: async () =>
+          buildRoutedTurn({
+            turnType: "planning_request",
+            action: "ask_clarification",
+            clarificationSlots: ["task", "time"],
+          }),
+      },
+    );
+
+    expect(response.status).toBe(200);
+    expect(conversationResponder).toHaveBeenCalledWith(
+      expect.objectContaining({
+        clarificationSlots: ["task", "time"],
+      }),
+    );
+  });
+
   it("preserves mutation behavior when the turn router explicitly returns mutation", async () => {
     process.env.TELEGRAM_WEBHOOK_SECRET = "test-webhook-secret";
 

apps/web/src/lib/server/telegram-webhook.ts

@@ -362,6 +362,7 @@ export async function handleTelegramWebhook(
       memorySummary,
       entityRegistry: conversationState?.entityRegistry ?? [],
       discourseState: conversationState?.discourseState ?? null,
+      clarificationSlots: routedWithContext.policy.clarificationSlots,
     });
 
     const outboundDelivery = await finalizeFollowUpMessage(

packages/integrations/src/openai.ts

@@ -59,6 +59,7 @@ export const conversationResponseInputSchema = z.object({
   memorySummary: z.string().nullable(),
   entityRegistry: z.array(conversationEntitySchema).optional().default([]),
   discourseState: conversationDiscourseStateSchema.nullable().optional(),
+  clarificationSlots: z.array(z.string().min(1)).optional(),
 });
 
 export const conversationResponseOutputSchema = z.object({
@@ -396,6 +397,7 @@ function buildConversationResponsePromptContext(
     memorySummary: context.memorySummary,
     entityRegistry: context.entityRegistry ?? [],
     discourseState: context.discourseState ?? null,
+    clarificationSlots: context.clarificationSlots ?? null,
   };
 }
 

packages/integrations/src/prompts/conversation-response.ts

@@ -21,11 +21,15 @@ export const conversationResponseSystemPrompt = buildPromptSpec([
       "The provided transcript and memory summary are continuity context only, not authoritative Atlas state.",
       "When entityRegistry or discourseState are present, use them as the primary reference-resolution aid for pronouns like 'it', 'that', or 'the other one'.",
       "When pending clarifications are present in discourseState, treat them as the current blocking questions and use them as the main guide for interpreting short follow-up replies.",
+      "When clarificationSlots is a non-empty array, it lists the specific slot names (e.g. 'time', 'task', 'day') the system needs before it can act on the request. Use clarificationSlots as the primary guide for what to ask about.",
     ],
   },
   {
     title: "Decision Rules",
     lines: [
+      "When clarificationSlots is present and non-empty, ask specifically about those slots. Frame the reply around the missing slot names rather than asking a generic follow-up.",
+      "When clarificationSlots is present, do not ask about slots that are NOT in the list. Focus narrowly on the listed missing slots.",
+      "When clarificationSlots is absent or empty, fall back to existing decision rules for determining what to ask.",
       "Use cautious phrasing when inferring from conversation context, such as 'it sounds like', 'if you mean', or 'from our recent exchange'.",
       "When the user asks whether Atlas already created, moved, scheduled, completed, or archived something, answer from recent conversational context rather than implied internal state.",
       "For write-adjacent questions on the conversation path, say that the recent exchange did not establish confirmed state instead of speaking as if Atlas knows the mutation did or did not happen in authoritative product state.",
@@ -72,6 +76,8 @@ export const conversationResponseSystemPrompt = buildPromptSpec([
       "If the user says 'schedule an oil change', do not ask follow-up questions about date, time, or location by default. Briefly acknowledge the intended scheduling action unless the task target itself is unclear.",
       "Good reply style for a clear bare scheduling request on the conversation path: 'It sounds like you want me to schedule the oil change at the next reasonable opening.'",
       "Good reply style for delegated slot choice on the conversation path: 'It sounds like you want me to schedule the oil change and choose the next open slot.'",
+      "If clarificationSlots is ['time'] and the user said 'schedule an oil change', respond like: 'When would you like me to schedule the oil change?'",
+      "If clarificationSlots is ['task', 'time'] and the user said 'schedule something tomorrow', respond like: 'What would you like me to schedule, and what time works for you?'",
     ],
   },
 ]);