feat: populate minimal parent conversation hint

Author: baum777

src/engagement/conversationBundle.ts

@@ -38,6 +38,12 @@ export interface ConversationBundleInput {
   sourceMetadata?: Record<string, unknown>;
 }
 
+export interface ConversationParentHint {
+  tweetId?: string;
+  conversationId?: string;
+  authorId?: string;
+}
+
 function readString(metadata: Record<string, unknown> | undefined, key: string): string | undefined {
   const value = metadata?.[key];
   return typeof value === "string" ? value : undefined;
@@ -74,6 +80,24 @@ function buildAuthorContext(input: ConversationBundleInput): ConversationAuthorC
   };
 }
 
+export function buildConversationParentRef(
+  hint: ConversationParentHint | undefined
+): ConversationParentRef | undefined {
+  if (!hint) {
+    return undefined;
+  }
+
+  if (!hint.tweetId && !hint.conversationId && !hint.authorId) {
+    return undefined;
+  }
+
+  return {
+    tweetId: hint.tweetId,
+    conversationId: hint.conversationId,
+    authorId: hint.authorId,
+  };
+}
+
 export function maybeBuildConversationBundle(input: ConversationBundleInput): ConversationBundle | undefined {
   const bundle: ConversationBundle = {
     sourceTweet: buildSourceTweet(input),

src/worker/pollMentions.ts

@@ -70,7 +70,10 @@ import {
   buildRawTriggerInputFromMention,
   toCanonicalExecutionInput,
 } from "../engagement/candidateBoundary.js";
-import { maybeBuildConversationBundle } from "../engagement/conversationBundle.js";
+import {
+  buildConversationParentRef,
+  maybeBuildConversationBundle,
+} from "../engagement/conversationBundle.js";
 import {
   runWritePreflight,
   releaseWritePreflight,
@@ -337,6 +340,12 @@ export async function processCanonicalMention(
   const engagementCandidate = buildEngagementCandidate(rawTriggerInput);
   const conversationBundle = maybeBuildConversationBundle({
     candidate: engagementCandidate,
+    parentRef: buildConversationParentRef({
+      tweetId:
+        mention.referenced_tweets?.find((ref) => ref.type === "replied_to" || ref.type === "quoted")
+          ?.id,
+      conversationId: mention.conversation_id ?? undefined,
+    }),
     sourceTweet: {
       tweetId: engagementCandidate.tweetId,
       conversationId: engagementCandidate.conversationId,

src/worker/pollTimelineEngagement.ts

@@ -15,7 +15,10 @@ import {
   buildRawTriggerInputFromTimelineCandidate,
   toCanonicalExecutionInput,
 } from "../engagement/candidateBoundary.js";
-import { maybeBuildConversationBundle } from "../engagement/conversationBundle.js";
+import {
+  buildConversationParentRef,
+  maybeBuildConversationBundle,
+} from "../engagement/conversationBundle.js";
 import { logInfo, logWarn } from "../ops/logger.js";
 import { isPostingDisabled } from "../ops/launchGate.js";
 import { withCircuitBreaker } from "../ops/llmCircuitBreaker.js";
@@ -368,6 +371,10 @@ export async function runTimelineEngagementIteration(): Promise<TimelineIteratio
         const engagementCandidate = buildEngagementCandidate(rawTriggerInput);
         const conversationBundle = maybeBuildConversationBundle({
           candidate: engagementCandidate,
+          parentRef: buildConversationParentRef({
+            tweetId: candidate.referencedTweetIds[0],
+            conversationId: candidate.conversationId,
+          }),
           sourceTweet: {
             tweetId: engagementCandidate.tweetId,
             conversationId: engagementCandidate.conversationId,

tests/engagement/candidateBoundary.test.ts

@@ -5,7 +5,10 @@ import {
   buildRawTriggerInputFromTimelineCandidate,
   toCanonicalExecutionInput,
 } from "../../src/engagement/candidateBoundary.js";
-import { maybeBuildConversationBundle } from "../../src/engagement/conversationBundle.js";
+import {
+  buildConversationParentRef,
+  maybeBuildConversationBundle,
+} from "../../src/engagement/conversationBundle.js";
 
 describe("candidateBoundary", () => {
   it("normalizes mention ingress into the shared candidate boundary", () => {
@@ -23,6 +26,10 @@ describe("candidateBoundary", () => {
     const candidate = buildEngagementCandidate(raw);
     const bundle = maybeBuildConversationBundle({
       candidate,
+      parentRef: buildConversationParentRef({
+        tweetId: "parent-mention-1",
+        conversationId: candidate.conversationId,
+      }),
       sourceTweet: {
         tweetId: candidate.tweetId,
         conversationId: candidate.conversationId,
@@ -44,6 +51,7 @@ describe("candidateBoundary", () => {
     expect(candidate.candidateId).toBe("mention-1");
     expect(candidate.normalizedText).toBe("Hello @Gnomes_onchain, can you help?");
     expect(bundle?.sourceTweet?.tweetId).toBe("mention-1");
+    expect(bundle?.parentRef?.tweetId).toBe("parent-mention-1");
     expect(bundle?.authorContext?.authorHandle).toBe("Alice");
     expect(canonical.event_id).toBe("mention-1");
     expect(canonical.trigger_type).toBe("mention");
@@ -92,6 +100,10 @@ describe("candidateBoundary", () => {
     const candidate = buildEngagementCandidate(raw);
     const bundle = maybeBuildConversationBundle({
       candidate,
+      parentRef: buildConversationParentRef({
+        tweetId: "parent-tweet-1",
+        conversationId: candidate.conversationId,
+      }),
       sourceTweet: {
         tweetId: candidate.tweetId,
         conversationId: candidate.conversationId,
@@ -113,6 +125,7 @@ describe("candidateBoundary", () => {
     expect(candidate.candidateId).toBe("timeline:tweet-1");
     expect(candidate.normalizedText).toBe("A thoughtful timeline reply with a clear question?");
     expect(bundle?.sourceTweet?.tweetId).toBe("tweet-1");
+    expect(bundle?.parentRef?.tweetId).toBe("parent-tweet-1");
     expect(bundle?.authorContext?.sourceAccount).toBe("timeline");
     expect(canonical.event_id).toBe("timeline:tweet-1");
     expect(canonical.trigger_type).toBe("reply");
@@ -133,9 +146,16 @@ describe("candidateBoundary", () => {
     };
     const candidate = buildEngagementCandidate(raw);
 
-    const bundle = maybeBuildConversationBundle({ candidate });
+    const bundle = maybeBuildConversationBundle({
+      candidate,
+      parentRef: buildConversationParentRef({
+        tweetId: "parent-2",
+        conversationId: candidate.conversationId,
+      }),
+    });
 
     expect(bundle?.sourceTweet?.tweetId).toBe("mention-2");
+    expect(bundle?.parentRef?.tweetId).toBe("parent-2");
     expect(bundle?.authorContext?.authorId).toBe("author-3");
     expect(bundle?.sourceMetadata?.authorHandle).toBe("alice");
   });

tests/integration/pipeline/mentionPipelineConsentFlow.test.ts

@@ -63,6 +63,7 @@ const maybeBuildConversationBundleMock = vi.fn(
         normalizedText: input.candidate.normalizedText,
         discoveredAt: input.candidate.discoveredAt,
       },
+    parentRef: input.parentRef,
     authorContext: input.authorContext,
     sourceMetadata: input.sourceMetadata ?? input.candidate.sourceMetadata,
   })
@@ -111,6 +112,8 @@ vi.mock("../../../src/engagement/candidateBoundary.js", () => ({
 }));
 
 vi.mock("../../../src/engagement/conversationBundle.js", () => ({
+  buildConversationParentRef: (hint: { tweetId?: string; conversationId?: string; authorId?: string }) =>
+    hint?.tweetId || hint?.conversationId || hint?.authorId ? hint : undefined,
   maybeBuildConversationBundle: maybeBuildConversationBundleMock,
 }));
 
@@ -187,6 +190,10 @@ describe("mention pipeline consent flow", () => {
     expect(buildRawTriggerInputMock).toHaveBeenCalledTimes(1);
     expect(buildEngagementCandidateMock).toHaveBeenCalledTimes(1);
     expect(maybeBuildConversationBundleMock).toHaveBeenCalledTimes(1);
+    expect(maybeBuildConversationBundleMock.mock.calls[0]?.[0].parentRef).toMatchObject({
+      tweetId: "bot-1",
+      conversationId: "conv-1",
+    });
     expect(toCanonicalExecutionInputMock).toHaveBeenCalledTimes(1);
     expect(toCanonicalExecutionInputMock.mock.calls[0]?.[1]).toBeDefined();
   });

tests/worker/pollTimelineEngagement.integration.test.ts

@@ -90,6 +90,7 @@ const maybeBuildConversationBundleMock = vi.fn(
         normalizedText: input.candidate.normalizedText,
         discoveredAt: input.candidate.discoveredAt,
       },
+    parentRef: input.parentRef,
     authorContext: input.authorContext,
     sourceMetadata: input.sourceMetadata ?? input.candidate.sourceMetadata,
   })
@@ -171,6 +172,8 @@ vi.mock("../../src/engagement/candidateBoundary.js", () => ({
 }));
 
 vi.mock("../../src/engagement/conversationBundle.js", () => ({
+  buildConversationParentRef: (hint: { tweetId?: string; conversationId?: string; authorId?: string }) =>
+    hint?.tweetId || hint?.conversationId || hint?.authorId ? hint : undefined,
   maybeBuildConversationBundle: maybeBuildConversationBundleMock,
 }));
 
@@ -334,6 +337,9 @@ describe("timeline engagement worker", () => {
     expect(handleEventMock).toHaveBeenCalledTimes(1);
     expect(replyMock).toHaveBeenCalledTimes(1);
     expect(maybeBuildConversationBundleMock).toHaveBeenCalledTimes(1);
+    expect(maybeBuildConversationBundleMock.mock.calls[0]?.[0].parentRef).toMatchObject({
+      conversationId: "conv-1",
+    });
     expect(buildRawTriggerInputMock).toHaveBeenCalledTimes(1);
     expect(buildEngagementCandidateMock).toHaveBeenCalledTimes(1);
     expect(toCanonicalExecutionInputMock).toHaveBeenCalledTimes(1);