Merge pull request #71 from MaxLinCode/claude/phase1-pending-write-operation

Replace committedSlots/resolvedContract with PendingWriteOperation

Author: MaxLinCode

apps/web/package.json

@@ -6,7 +6,8 @@
     "build": "next build",
     "lint": "biome check src next.config.ts vitest.config.mts",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run",
+    "vitest": "vitest"
   },
   "dependencies": {
     "@atlas/core": "workspace:*",

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

@@ -1,16 +1,12 @@
 import type {
   ConversationEntity,
   InboxPlanningOutput,
+  PendingWriteOperation,
   RoutedTurn,
-  TimeSpec,
   TurnInterpretationType,
   TurnPolicyAction,
 } from "@atlas/core";
 
-function t(hour: number, minute: number): TimeSpec {
-  return { kind: "absolute", hour, minute };
-}
-
 import {
   getDefaultFollowUpRuntimeStore,
   getDefaultGoogleCalendarConnectionStore,
@@ -155,8 +151,8 @@ function buildRoutedTurn(input: {
   confidence?: number;
   ambiguity?: "none" | "low" | "high";
   resolvedProposalId?: string;
-  committedSlots?: Record<string, string | number | TimeSpec>;
   clarificationSlots?: string[];
+  resolvedOperation?: PendingWriteOperation;
 }): RoutedTurn {
   return {
     interpretation: {
@@ -186,10 +182,12 @@ function buildRoutedTurn(input: {
         : input.action === "execute_mutation"
           ? { mutationInputSource: "direct_user_turn" as const }
           : {}),
-      committedSlots: input.committedSlots ?? {},
       ...(input.clarificationSlots
         ? { clarificationSlots: input.clarificationSlots }
         : {}),
+      ...(input.resolvedOperation
+        ? { resolvedOperation: input.resolvedOperation }
+        : {}),
     },
   };
 }
@@ -1192,7 +1190,18 @@ describe("telegram webhook route", () => {
             turnType: "confirmation",
             action: "recover_and_execute",
             resolvedProposalId: "proposal-1",
-            committedSlots: { time: t(15, 0) },
+            resolvedOperation: {
+              operationKind: "plan",
+              targetRef: null,
+              resolvedFields: {
+                scheduleFields: {
+                  time: { kind: "absolute", hour: 15, minute: 0 },
+                },
+              },
+              missingFields: [],
+              originatingText: "Schedule the dentist reminder",
+              startedAt: new Date().toISOString(),
+            },
           }),
       },
     );

apps/web/src/lib/server/conversation-state.test.ts

@@ -1,11 +1,29 @@
-import type { ConversationStateSnapshot, TimeSpec } from "@atlas/core";
+import type {
+  ConversationStateSnapshot,
+  PendingWriteOperation,
+  TimeSpec,
+} from "@atlas/core";
 import type { ProcessedInboxResult } from "@atlas/db";
 import { describe, expect, it } from "vitest";
 
 function t(hour: number, minute: number): TimeSpec {
   return { kind: "absolute", hour, minute };
 }
 
+function buildPendingWriteOperation(
+  overrides?: Partial<PendingWriteOperation>,
+): PendingWriteOperation {
+  return {
+    operationKind: "plan",
+    targetRef: null,
+    resolvedFields: {},
+    missingFields: [],
+    originatingText: "schedule gym tomorrow",
+    startedAt: "2026-03-22T16:00:00.000Z",
+    ...overrides,
+  };
+}
+
 import {
   deriveConversationReplyState,
   deriveMutationState,
@@ -41,15 +59,14 @@ describe("deriveConversationReplyState", () => {
       snapshot: buildSnapshot(),
       policy: {
         action: "ask_clarification",
-        clarificationSlots: ["time"],
-        committedSlots: {},
+        clarificationSlots: ["scheduleFields.time"],
       },
       interpretation: {
         turnType: "planning_request",
         confidence: 0.58,
         resolvedEntityIds: [],
         ambiguity: "high",
-        missingSlots: ["time"],
+        missingFields: ["scheduleFields.time"],
       },
       reply: "What time should I schedule the Malaysia trip planning?",
       userTurnText: "schedule malaysia trip planning tomorrow",
@@ -62,12 +79,12 @@ describe("deriveConversationReplyState", () => {
       kind: "clarification",
       status: "active",
       data: {
-        reason: "time",
+        reason: "scheduleFields.time",
       },
     });
     expect(result.discourseState?.pending_clarifications).toEqual([
       expect.objectContaining({
-        slot: "time",
+        slot: "scheduleFields.time",
         status: "pending",
       }),
     ]);
@@ -80,7 +97,6 @@ describe("deriveConversationReplyState", () => {
       policy: {
         action: "ask_clarification",
         clarificationSlots: ["proposal"],
-        committedSlots: {},
       },
       interpretation: {
         turnType: "confirmation",
@@ -104,14 +120,13 @@ describe("deriveConversationReplyState", () => {
       snapshot: buildSnapshot(),
       policy: {
         action: "ask_clarification",
-        committedSlots: {},
       },
       interpretation: {
         turnType: "unknown",
         confidence: 0.42,
         resolvedEntityIds: [],
         ambiguity: "high",
-        missingSlots: ["unknown"],
+        missingFields: ["unknown"],
       },
       reply: "Can you clarify what you want me to change?",
       userTurnText: "do it",
@@ -165,7 +180,6 @@ describe("deriveConversationReplyState", () => {
       snapshot,
       policy: {
         action: "present_proposal",
-        committedSlots: {},
       },
       interpretation: {
         turnType: "clarification_answer",
@@ -197,47 +211,40 @@ describe("deriveConversationReplyState", () => {
     expect(result.discourseState?.mode).toBe("confirming");
   });
 
-  it("persists pending_write_contract when resolvedContract is provided", () => {
-    const contract = {
-      requiredSlots: ["day", "time"] as (
-        | "day"
-        | "time"
-        | "duration"
-        | "target"
-      )[],
-      intentKind: "plan" as const,
-    };
+  it("persists pending_write_operation when resolvedOperation is provided", () => {
+    const op = buildPendingWriteOperation({
+      resolvedFields: { scheduleFields: { day: "tomorrow" } },
+      missingFields: ["scheduleFields.time"],
+    });
 
     const result = deriveConversationReplyState({
       snapshot: buildSnapshot(),
       policy: {
         action: "ask_clarification",
-        clarificationSlots: ["time"],
-        committedSlots: { day: "tomorrow" },
-        resolvedContract: contract,
+        clarificationSlots: ["scheduleFields.time"],
+        resolvedOperation: op,
       },
       interpretation: {
         turnType: "planning_request",
         confidence: 0.58,
         resolvedEntityIds: [],
         ambiguity: "high",
-        missingSlots: ["time"],
+        missingFields: ["scheduleFields.time"],
       },
       reply: "What time should I schedule it?",
       userTurnText: "schedule gym tomorrow",
       summaryText: null,
       occurredAt: "2026-03-22T16:05:00.000Z",
     });
 
-    expect(result.discourseState?.pending_write_contract).toEqual(contract);
+    expect(result.discourseState?.pending_write_operation).toEqual(op);
   });
 
-  it("does not set pending_write_contract when resolvedContract is absent", () => {
+  it("does not set pending_write_operation when resolvedOperation is absent", () => {
     const result = deriveConversationReplyState({
       snapshot: buildSnapshot(),
       policy: {
         action: "reply_only",
-        committedSlots: {},
       },
       interpretation: {
         turnType: "informational",
@@ -251,7 +258,7 @@ describe("deriveConversationReplyState", () => {
       occurredAt: "2026-03-22T16:05:00.000Z",
     });
 
-    expect(result.discourseState?.pending_write_contract).toBeUndefined();
+    expect(result.discourseState?.pending_write_operation).toBeUndefined();
   });
 
   it("clears active clarifications when a clarification_answer resolves all slots", () => {
@@ -294,7 +301,12 @@ describe("deriveConversationReplyState", () => {
       snapshot,
       policy: {
         action: "present_proposal",
-        committedSlots: { day: "tomorrow", time: t(17, 0) },
+        resolvedOperation: buildPendingWriteOperation({
+          resolvedFields: {
+            scheduleFields: { day: "tomorrow", time: t(17, 0) },
+          },
+          missingFields: [],
+        }),
       },
       interpretation: {
         turnType: "clarification_answer",
@@ -428,15 +440,13 @@ describe("deriveMutationState", () => {
     expect(result.discourseState.mode).toBe("editing");
   });
 
-  it("clears resolved_slots and pending_write_contract on successful mutation", () => {
+  it("clears pending_write_operation on successful mutation", () => {
     const snapshot = buildSnapshot();
     snapshot.discourseState = {
       ...snapshot.discourseState!,
-      resolved_slots: { day: "tomorrow", time: t(17, 0) },
-      pending_write_contract: {
-        requiredSlots: ["day", "time"],
-        intentKind: "plan",
-      },
+      pending_write_operation: buildPendingWriteOperation({
+        resolvedFields: { scheduleFields: { day: "tomorrow", time: t(17, 0) } },
+      }),
     };
 
     const processing: ProcessedInboxResult = {
@@ -504,19 +514,18 @@ describe("deriveMutationState", () => {
       occurredAt: "2026-03-22T16:10:00.000Z",
     });
 
-    expect(result.discourseState.resolved_slots).toEqual({});
-    expect(result.discourseState.pending_write_contract).toBeUndefined();
+    expect(result.discourseState.pending_write_operation).toBeUndefined();
   });
 
-  it("preserves resolved_slots and pending_write_contract on needs_clarification", () => {
+  it("preserves pending_write_operation on needs_clarification", () => {
+    const op = buildPendingWriteOperation({
+      resolvedFields: { scheduleFields: { day: "tomorrow" } },
+      missingFields: ["scheduleFields.time"],
+    });
     const snapshot = buildSnapshot();
     snapshot.discourseState = {
       ...snapshot.discourseState!,
-      resolved_slots: { day: "tomorrow" },
-      pending_write_contract: {
-        requiredSlots: ["day", "time"],
-        intentKind: "plan",
-      },
+      pending_write_operation: op,
     };
 
     const processing: ProcessedInboxResult = {
@@ -549,10 +558,6 @@ describe("deriveMutationState", () => {
       occurredAt: "2026-03-22T16:10:00.000Z",
     });
 
-    expect(result.discourseState.resolved_slots).toEqual({ day: "tomorrow" });
-    expect(result.discourseState.pending_write_contract).toEqual({
-      requiredSlots: ["day", "time"],
-      intentKind: "plan",
-    });
+    expect(result.discourseState.pending_write_operation).toEqual(op);
   });
 });

apps/web/src/lib/server/conversation-state.ts

@@ -21,11 +21,7 @@ type DeriveConversationReplyStateInput = {
   snapshot: ConversationStateSnapshot;
   policy: Pick<
     TurnPolicyDecision,
-    | "action"
-    | "clarificationSlots"
-    | "targetProposalId"
-    | "committedSlots"
-    | "resolvedContract"
+    "action" | "clarificationSlots" | "targetProposalId" | "resolvedOperation"
   > & {
     action: Extract<
       TurnPolicyAction,
@@ -109,7 +105,8 @@ export function deriveConversationReplyState(
           confirmationRequired: true,
           originatingTurnText: input.userTurnText,
           missingSlots: input.policy.clarificationSlots,
-          slotSnapshot: input.policy.committedSlots ?? {},
+          slotSnapshot:
+            input.policy.resolvedOperation?.resolvedFields.scheduleFields ?? {},
         },
       }),
     );
@@ -176,14 +173,10 @@ export function deriveConversationReplyState(
     },
   ).state;
 
-  const committedSlots = input.policy.committedSlots;
   const nextDiscourseState = {
     ...updatedDiscourseState,
-    ...(committedSlots && Object.keys(committedSlots).length > 0
-      ? { resolved_slots: committedSlots }
-      : {}),
-    ...(input.policy.resolvedContract
-      ? { pending_write_contract: input.policy.resolvedContract }
+    ...(input.policy.resolvedOperation
+      ? { pending_write_operation: input.policy.resolvedOperation }
       : {}),
   };
 
@@ -319,8 +312,7 @@ export function deriveMutationState(input: DeriveMutationStateInput) {
   const finalDiscourseState = isFlowComplete
     ? {
         ...discourseState,
-        resolved_slots: {},
-        pending_write_contract: undefined,
+        pending_write_operation: undefined,
       }
     : discourseState;
 
@@ -470,7 +462,11 @@ function upsertActiveProposalEntity(
   return nextProposal;
 }
 
-const PERSISTABLE_SLOT_KEYS = new Set(["day", "time", "duration", "target"]);
+const PERSISTABLE_SLOT_KEYS = new Set([
+  "scheduleFields.day",
+  "scheduleFields.time",
+  "scheduleFields.duration",
+]);
 
 function derivePersistableClarificationSlots(slots: string[] | undefined) {
   if (!slots) {