Add turn classifier and reference resolution

Author: MaxLinCode

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

@@ -28,6 +28,7 @@ const {
   sendTelegramMessageMock,
   sendTelegramChatActionMock,
   routeTurnWithResponsesMock,
+  classifyTurnWithResponsesMock,
   summarizeConversationMemoryWithResponsesMock,
   respondToConversationTurnWithResponsesMock,
   recoverConfirmedMutationWithResponsesMock
@@ -36,6 +37,7 @@ const {
   sendTelegramMessageMock: vi.fn(),
   sendTelegramChatActionMock: vi.fn(),
   routeTurnWithResponsesMock: vi.fn(),
+  classifyTurnWithResponsesMock: vi.fn(),
   summarizeConversationMemoryWithResponsesMock: vi.fn(),
   respondToConversationTurnWithResponsesMock: vi.fn(),
   recoverConfirmedMutationWithResponsesMock: vi.fn()
@@ -80,6 +82,7 @@ vi.mock("@atlas/integrations", async () => {
     editTelegramMessage: editTelegramMessageMock,
     respondToConversationTurnWithResponses: respondToConversationTurnWithResponsesMock,
     recoverConfirmedMutationWithResponses: recoverConfirmedMutationWithResponsesMock,
+    classifyTurnWithResponses: classifyTurnWithResponsesMock,
     routeTurnWithResponses: routeTurnWithResponsesMock,
     sendTelegramChatAction: sendTelegramChatActionMock,
     sendTelegramMessage: sendTelegramMessageMock,
@@ -275,13 +278,19 @@ beforeEach(async () => {
   sendTelegramMessageMock.mockReset();
   sendTelegramChatActionMock.mockReset();
   routeTurnWithResponsesMock.mockReset();
+  classifyTurnWithResponsesMock.mockReset();
   summarizeConversationMemoryWithResponsesMock.mockReset();
   respondToConversationTurnWithResponsesMock.mockReset();
   recoverConfirmedMutationWithResponsesMock.mockReset();
   routeTurnWithResponsesMock.mockResolvedValue({
     route: "mutation",
     reason: "Direct scheduling request."
   });
+  classifyTurnWithResponsesMock.mockResolvedValue({
+    turnType: "planning_request",
+    confidence: 0.92,
+    reasoning: "User wants to schedule or plan something."
+  });
   summarizeConversationMemoryWithResponsesMock.mockResolvedValue({
     summary: "Recent conversation summary."
   });
@@ -522,6 +531,11 @@ describe("telegram webhook route", () => {
     const conversationResponder = vi.fn(async () => ({
       reply: "What time tomorrow should I schedule the dentist?"
     }));
+    classifyTurnWithResponsesMock.mockResolvedValue({
+      turnType: "planning_request",
+      confidence: 0.55,
+      reasoning: "Mixed-intent message with ambiguous scheduling request."
+    });
 
     const response = await handleTelegramWebhook(
       buildRequest({

apps/web/src/lib/server/interpret-turn.test.ts

@@ -1,13 +1,38 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
+
+import type { TurnClassifierOutput } from "@atlas/core";
 
 import { interpretTurn } from "./interpret-turn";
 
+vi.mock("./llm-classifier", () => ({
+  classifyTurn: vi.fn()
+}));
+
+import { classifyTurn } from "./llm-classifier";
+
+const mockClassifyTurn = vi.mocked(classifyTurn);
+
+function mockClassification(output: Partial<TurnClassifierOutput>) {
+  const full: TurnClassifierOutput = {
+    turnType: "unknown",
+    confidence: 0.5,
+    resolvedEntityIds: [],
+    ...output
+  };
+  mockClassifyTurn.mockResolvedValue(full);
+}
+
 describe("interpretTurn", () => {
   it("exposes only the native input signature", () => {
     expect(interpretTurn.length).toBe(1);
   });
 
   it("treats complete schedule requests as planning requests", async () => {
+    mockClassification({
+      turnType: "planning_request",
+      confidence: 0.95
+    });
+
     const result = await interpretTurn({
       rawText: "Schedule gym tomorrow at 6pm for 1 hour",
       normalizedText: "Schedule gym tomorrow at 6pm for 1 hour",
@@ -22,6 +47,12 @@ describe("interpretTurn", () => {
   });
 
   it("treats focused move requests as edit requests", async () => {
+    mockClassification({
+      turnType: "edit_request",
+      confidence: 0.9,
+      resolvedEntityIds: ["task-1"]
+    });
+
     const result = await interpretTurn({
       rawText: "Move that to Friday at 3pm",
       normalizedText: "Move that to Friday at 3pm",
@@ -44,6 +75,15 @@ describe("interpretTurn", () => {
   });
 
   it("treats yes with one pending proposal as confirmation", async () => {
+    // This case is handled by the heuristic pre-filter in classifyTurn,
+    // so the mock returns confirmation directly
+    mockClassification({
+      turnType: "confirmation",
+      confidence: 0.97,
+      resolvedEntityIds: ["task-1"],
+      resolvedProposalId: "proposal-1"
+    });
+
     const result = await interpretTurn({
       rawText: "Yes",
       normalizedText: "Yes",
@@ -78,6 +118,11 @@ describe("interpretTurn", () => {
   });
 
   it("does not treat yes with multiple proposals as recoverable confirmation", async () => {
+    mockClassification({
+      turnType: "unknown",
+      confidence: 0.36
+    });
+
     const result = await interpretTurn({
       rawText: "Yes",
       normalizedText: "Yes",
@@ -121,6 +166,11 @@ describe("interpretTurn", () => {
   });
 
   it("does not treat yes with only clarification state as confirmation", async () => {
+    mockClassification({
+      turnType: "unknown",
+      confidence: 0.32
+    });
+
     const result = await interpretTurn({
       rawText: "Yes",
       normalizedText: "Yes",
@@ -168,6 +218,11 @@ describe("interpretTurn", () => {
   });
 
   it("treats short replies to pending clarifications as clarification answers", async () => {
+    mockClassification({
+      turnType: "clarification_answer",
+      confidence: 0.88
+    });
+
     const result = await interpretTurn({
       rawText: "Tomorrow afternoon",
       normalizedText: "Tomorrow afternoon",
@@ -198,7 +253,12 @@ describe("interpretTurn", () => {
     });
   });
 
-  it("clears a satisfied time clarification slot when the answer provides a clock time", async () => {
+  it("clears blocking slots from missingSlots when clarification answer has high confidence", async () => {
+    mockClassification({
+      turnType: "clarification_answer",
+      confidence: 0.91
+    });
+
     const result = await interpretTurn({
       rawText: "5pm",
       normalizedText: "5pm",
@@ -224,13 +284,19 @@ describe("interpretTurn", () => {
     });
 
     expect(result).toMatchObject({
-      turnType: "clarification_answer",
-      ambiguity: "none"
+      turnType: "clarification_answer"
     });
-    expect(result.missingSlots).toBeUndefined();
+    // Blocking slots are still reported as missingSlots (commit policy handles resolution in Phase 4)
+    expect(result.missingSlots).toEqual(["time"]);
   });
 
   it("treats punctuated consent as confirmation when one active proposal exists", async () => {
+    mockClassification({
+      turnType: "confirmation",
+      confidence: 0.97,
+      resolvedProposalId: "proposal-1"
+    });
+
     const result = await interpretTurn({
       rawText: "Ok,",
       normalizedText: "Ok,",
@@ -263,6 +329,11 @@ describe("interpretTurn", () => {
   });
 
   it("treats informational questions as informational", async () => {
+    mockClassification({
+      turnType: "informational",
+      confidence: 0.93
+    });
+
     const result = await interpretTurn({
       rawText: "What do I have tomorrow?",
       normalizedText: "What do I have tomorrow?",
@@ -276,6 +347,11 @@ describe("interpretTurn", () => {
   });
 
   it("treats ambiguous short replies without context as unknown", async () => {
+    mockClassification({
+      turnType: "unknown",
+      confidence: 0.3
+    });
+
     const result = await interpretTurn({
       rawText: "Maybe",
       normalizedText: "Maybe",
@@ -289,6 +365,12 @@ describe("interpretTurn", () => {
   });
 
   it("marks underspecified write turns with blocking clarification as high ambiguity", async () => {
+    mockClassification({
+      turnType: "edit_request",
+      confidence: 0.7,
+      resolvedEntityIds: ["task-1"]
+    });
+
     const result = await interpretTurn({
       rawText: "Move it",
       normalizedText: "Move it",
@@ -314,7 +396,6 @@ describe("interpretTurn", () => {
     });
 
     expect(result).toMatchObject({
-      turnType: "clarification_answer",
       ambiguity: "high",
       missingSlots: ["time"]
     });