Merge pull request #49 from MaxLinCode/codex/native-turn-routing

feat: implement native turn interpretation and policy routing

Author: MaxLinCode

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

@@ -23,13 +23,23 @@ import { getDefaultCalendarAdapter, resetCalendarAdapterForTests } from "@atlas/
 
 import { handleTelegramWebhook } from "@/lib/server/telegram-webhook";
 
-const { editTelegramMessageMock, sendTelegramMessageMock, sendTelegramChatActionMock, routeTurnWithResponsesMock } =
-  vi.hoisted(() => ({
-    editTelegramMessageMock: vi.fn(),
+const {
+  editTelegramMessageMock,
+  sendTelegramMessageMock,
+  sendTelegramChatActionMock,
+  routeTurnWithResponsesMock,
+  summarizeConversationMemoryWithResponsesMock,
+  respondToConversationTurnWithResponsesMock,
+  recoverConfirmedMutationWithResponsesMock
+} = vi.hoisted(() => ({
+  editTelegramMessageMock: vi.fn(),
   sendTelegramMessageMock: vi.fn(),
   sendTelegramChatActionMock: vi.fn(),
-  routeTurnWithResponsesMock: vi.fn()
-  }));
+  routeTurnWithResponsesMock: vi.fn(),
+  summarizeConversationMemoryWithResponsesMock: vi.fn(),
+  respondToConversationTurnWithResponsesMock: vi.fn(),
+  recoverConfirmedMutationWithResponsesMock: vi.fn()
+}));
 
 vi.mock("@atlas/integrations", async () => {
   const actual = await vi.importActual<typeof import("@atlas/integrations")>("@atlas/integrations");
@@ -68,9 +78,12 @@ vi.mock("@atlas/integrations", async () => {
       ]
     }),
     editTelegramMessage: editTelegramMessageMock,
+    respondToConversationTurnWithResponses: respondToConversationTurnWithResponsesMock,
+    recoverConfirmedMutationWithResponses: recoverConfirmedMutationWithResponsesMock,
     routeTurnWithResponses: routeTurnWithResponsesMock,
     sendTelegramChatAction: sendTelegramChatActionMock,
-    sendTelegramMessage: sendTelegramMessageMock
+    sendTelegramMessage: sendTelegramMessageMock,
+    summarizeConversationMemoryWithResponses: summarizeConversationMemoryWithResponsesMock
   };
 });
 
@@ -262,10 +275,25 @@ beforeEach(async () => {
   sendTelegramMessageMock.mockReset();
   sendTelegramChatActionMock.mockReset();
   routeTurnWithResponsesMock.mockReset();
+  summarizeConversationMemoryWithResponsesMock.mockReset();
+  respondToConversationTurnWithResponsesMock.mockReset();
+  recoverConfirmedMutationWithResponsesMock.mockReset();
   routeTurnWithResponsesMock.mockResolvedValue({
     route: "mutation",
     reason: "Direct scheduling request."
   });
+  summarizeConversationMemoryWithResponsesMock.mockResolvedValue({
+    summary: "Recent conversation summary."
+  });
+  respondToConversationTurnWithResponsesMock.mockResolvedValue({
+    reply: "Mocked conversation reply."
+  });
+  recoverConfirmedMutationWithResponsesMock.mockResolvedValue({
+    outcome: "needs_clarification",
+    recoveredText: null,
+    reason: "Mocked recovery fallback.",
+    userReplyMessage: "Could you clarify what you want me to change?"
+  });
   sendTelegramMessageMock.mockResolvedValue({
     ok: true,
     result: {
@@ -491,6 +519,9 @@ describe("telegram webhook route", () => {
 
   it("lets mixed-intent messages fall through to the normal router even with outstanding followups", async () => {
     const { store, followUpStore } = await seedOutstandingFollowUpBundle(["Review launch checklist", "Send investor update"]);
+    const conversationResponder = vi.fn(async () => ({
+      reply: "What time tomorrow should I schedule the dentist?"
+    }));
 
     const response = await handleTelegramWebhook(
       buildRequest({
@@ -507,14 +538,25 @@ describe("telegram webhook route", () => {
         store,
         followUpStore,
         calendar: getDefaultCalendarAdapter(),
-        primeProcessingStore: seedInboxItemForProcessingTests
+        primeProcessingStore: seedInboxItemForProcessingTests,
+        conversationResponder
       }
     );
 
     expect(response.status).toBe(200);
-    expect(routeTurnWithResponsesMock).toHaveBeenCalledTimes(1);
-    expect((response.body as { processing: { outcome: string } }).processing.outcome).toBe("planned");
+    expect(response.body).toMatchObject({
+      processing: {
+        outcome: "conversation_replied",
+        reply: "What time tomorrow should I schedule the dentist?"
+      },
+      routing: {
+        policy: {
+          action: "ask_clarification"
+        }
+      }
+    });
     expect(listTasksForTests().filter((task) => task.lifecycleState === "done")).toHaveLength(0);
+    expect(conversationResponder).toHaveBeenCalledTimes(1);
   });
 
   it("also gates /start for unlinked users", async () => {
@@ -806,6 +848,58 @@ describe("telegram webhook route", () => {
     expect(editTelegramMessageMock).toHaveBeenCalledTimes(1);
   });
 
+  it("does not keep clear scheduling requests in discuss-first mode", async () => {
+    process.env.TELEGRAM_WEBHOOK_SECRET = "test-webhook-secret";
+
+    const response = await handleTelegramWebhook(
+      buildRequest({
+        update_id: 145,
+        message: {
+          message_id: 110,
+          date: 1_700_000_020,
+          text: "Schedule gym tomorrow at 6pm for 1 hour",
+          chat: {
+            id: 999,
+            type: "private"
+          },
+          from: {
+            id: 123,
+            is_bot: false,
+            first_name: "Max",
+            last_name: "Lin"
+          }
+        }
+      }),
+      {
+        store: getDefaultInboxProcessingStore(),
+        calendar: getDefaultCalendarAdapter(),
+        primeProcessingStore: seedInboxItemForProcessingTests
+      }
+    );
+
+    expect(response.status).toBe(200);
+    expect(response.body).toMatchObject({
+      accepted: true,
+      turnRoute: "mutation",
+      routing: {
+        interpretation: {
+          turnType: "planning_request",
+          ambiguity: "none"
+        },
+        policy: {
+          action: "execute_mutation"
+        }
+      },
+      processing: {
+        outcome: "planned"
+      }
+    });
+    expect(sendTelegramMessageMock).toHaveBeenCalledWith({
+      chatId: "999",
+      text: "Checking your schedule"
+    });
+  });
+
   it("treats confirmed mutation turns as write-capable when recovery finds one concrete proposal", async () => {
     process.env.TELEGRAM_WEBHOOK_SECRET = "test-webhook-secret";
     await recordOutgoingTelegramMessageIfNew({

apps/web/src/lib/server/decide-turn-policy.test.ts

@@ -24,14 +24,14 @@ describe("decideTurnPolicy", () => {
     });
   });
 
-  it("asks for clarification when write intent still has missing slots", () => {
+  it("asks for clarification when a scheduling request is still missing required slots", () => {
     expect(
       decideTurnPolicy({
         interpretation: {
           turnType: "planning_request",
-          confidence: 0.7,
+          confidence: 0.58,
           resolvedEntityIds: [],
-          ambiguity: "low",
+          ambiguity: "high",
           missingSlots: ["time"]
         },
         routingContext: {
@@ -46,28 +46,28 @@ describe("decideTurnPolicy", () => {
     });
   });
 
-  it("presents a proposal for medium-confidence write intent", () => {
+  it("does not force proposal mode for low-confidence writes alone", () => {
     expect(
       decideTurnPolicy({
         interpretation: {
           turnType: "planning_request",
           confidence: 0.68,
           resolvedEntityIds: [],
-          ambiguity: "low"
+          ambiguity: "none"
         },
         routingContext: {
-          rawText: "Could we move it to tomorrow morning?",
-          normalizedText: "Could we move it to tomorrow morning?",
+          rawText: "Schedule gym tomorrow at 6pm",
+          normalizedText: "Schedule gym tomorrow at 6pm",
           recentTurns: []
         }
       })
     ).toMatchObject({
-      action: "present_proposal",
-      requiresConfirmation: true
+      action: "execute_mutation",
+      requiresConfirmation: false
     });
   });
 
-  it("executes direct confident write intent", () => {
+  it("executes complete scheduling requests with no ambiguity", () => {
     expect(
       decideTurnPolicy({
         interpretation: {
@@ -77,8 +77,8 @@ describe("decideTurnPolicy", () => {
           ambiguity: "none"
         },
         routingContext: {
-          rawText: "Schedule gym tomorrow evening",
-          normalizedText: "Schedule gym tomorrow evening",
+          rawText: "Schedule gym tomorrow at 6pm for 1 hour",
+          normalizedText: "Schedule gym tomorrow at 6pm for 1 hour",
           recentTurns: []
         }
       })
@@ -101,7 +101,23 @@ describe("decideTurnPolicy", () => {
         routingContext: {
           rawText: "Yes",
           normalizedText: "Yes",
-          recentTurns: []
+          recentTurns: [],
+          entityRegistry: [
+            {
+              id: "proposal-1",
+              conversationId: "conversation-1",
+              kind: "proposal_option",
+              label: "Schedule it at 3pm",
+              status: "active",
+              createdAt: "2026-03-20T16:00:00.000Z",
+              updatedAt: "2026-03-20T16:00:00.000Z",
+              data: {
+                route: "conversation_then_mutation",
+                replyText: "Would you like me to schedule it at 3pm?",
+                confirmationRequired: true
+              }
+            }
+          ]
         }
       })
     ).toMatchObject({
@@ -110,45 +126,63 @@ describe("decideTurnPolicy", () => {
     });
   });
 
-  it("falls back to clarification when confirmation has no recoverable proposal", () => {
+  it("asks for clarification on ambiguous write-like turns", () => {
     expect(
       decideTurnPolicy({
         interpretation: {
-          turnType: "confirmation",
-          confidence: 0.4,
-          resolvedEntityIds: [],
-          ambiguity: "high"
+          turnType: "edit_request",
+          confidence: 0.6,
+          resolvedEntityIds: ["task-1"],
+          ambiguity: "high",
+          ambiguityReason: "Underspecified edit."
         },
         routingContext: {
-          rawText: "Yes",
-          normalizedText: "Yes",
+          rawText: "Move it",
+          normalizedText: "Move it",
           recentTurns: []
         }
       })
     ).toMatchObject({
-      action: "ask_clarification",
-      clarificationSlots: ["proposal"]
+      action: "ask_clarification"
     });
   });
 
-  it("asks for clarification on high-ambiguity write-like turns", () => {
+  it("uses present_proposal only for explicit confirmation-required policy", () => {
     expect(
       decideTurnPolicy({
         interpretation: {
-          turnType: "edit_request",
-          confidence: 0.6,
+          turnType: "planning_request",
+          confidence: 0.93,
           resolvedEntityIds: ["task-1"],
-          ambiguity: "high",
-          ambiguityReason: "Underspecified edit."
+          resolvedProposalId: "proposal-1",
+          ambiguity: "none"
         },
         routingContext: {
-          rawText: "Move it",
-          normalizedText: "Move it",
-          recentTurns: []
+          rawText: "Schedule it tomorrow at 6pm",
+          normalizedText: "Schedule it tomorrow at 6pm",
+          recentTurns: [],
+          entityRegistry: [
+            {
+              id: "proposal-1",
+              conversationId: "conversation-1",
+              kind: "proposal_option",
+              label: "Schedule it tomorrow at 6pm",
+              status: "active",
+              createdAt: "2026-03-20T16:00:00.000Z",
+              updatedAt: "2026-03-20T16:00:00.000Z",
+              data: {
+                route: "conversation_then_mutation",
+                replyText: "Would you like me to schedule it tomorrow at 6pm?",
+                confirmationRequired: true,
+                targetEntityId: "task-1"
+              }
+            }
+          ]
         }
       })
     ).toMatchObject({
-      action: "ask_clarification"
+      action: "present_proposal",
+      requiresConfirmation: true
     });
   });
 });