diff --git a/.agents/skills/verify-t3code/features/README.md b/.agents/skills/verify-t3code/features/README.md index fa7afbe8be17f..90df92fa2adbc 100644 --- a/.agents/skills/verify-t3code/features/README.md +++ b/.agents/skills/verify-t3code/features/README.md @@ -59,3 +59,8 @@ Desktop (Electron) shell, mobile app, linked remote machines (Connections > Add environment), Pull Request linking to a thread, previews and the in-app Browser panel, SnapShots, Integrations browser import, Agents panel, composer attachments and queued follow-ups, diff panel, git actions. Each needs a feature file when someone drives it. + +The last-seen marker ([seen-marker.md](seen-marker.md)) is also not on this drive. +Nothing in the window shows it: a focused 2 second dwell only updates device memory, +and the catch-up line is added to the provider prompt on the next send. The unit +tests are the proof. diff --git a/.agents/skills/verify-t3code/features/seen-marker.md b/.agents/skills/verify-t3code/features/seen-marker.md new file mode 100644 index 0000000000000..c7522e0306b9f --- /dev/null +++ b/.agents/skills/verify-t3code/features/seen-marker.md @@ -0,0 +1,51 @@ +# Last seen by a human + +A founder who leaves a thread and comes back should be caught up only on what they +did not see. The app remembers the newest message that stayed on screen for about +2 seconds in a focused, visible window. The next message they send tells the agent +where they left off. Scrolling never starts a turn, and a bot reading the thread +never counts as a view. + +## Sub-features + +- `seen-marker.dwell`: the newest on-screen message is remembered after 2 seconds, + and a shorter look is not. +- `seen-marker.focus`: a hidden, blurred, or backgrounded window does not count. +- `seen-marker.send`: the next send on that thread carries the marker, and the + provider prompt says who was last seen and how many assistant messages since + are unseen. A slash command stays first so it still runs; other text keeps + the catch-up in front. +- `seen-marker.quiet`: scrolling and dwelling dispatch no command and open no socket. +- `seen-marker.bots`: a thread read, and a send that did not come from the app, + carry no marker. + +## How to get to it (user POV) + +- Web and desktop: open a server thread and leave the window focused. Mobile: open + the thread with the app in the foreground. +- There is no control, badge, or settings path. The timeline does not change. + +## Driving it with `browser.mjs` + +Not driven. The marker is not rendered, so a browser pass cannot see it. A send +through the mock provider would only show it if the mock echoed its prompt, and +this drive does not do that. + +## Gotchas + +- The memory is per device and per app launch. A reload, or reading on one device + and sending from another, can repeat a catch-up or skip one. It never hides a + message. +- Bot and MCP reads do not run this client code. MCP sends do not attach a marker. +- Compact on the open thread is a send, so it carries the marker. A brand-new + thread does not. The catch-up follows `/compact` instead of leading it. +- A reply that is still streaming does not count. The previous finished message + on screen can. + +## Proves it works + +`packages/client-runtime/src/seenMarker.test.ts`, +`apps/web/src/hooks/useSeenMarkerTracking.test.ts`, +`apps/mobile/src/features/threads/useThreadSeenMarker.test.ts`, +`packages/shared/src/seenMarker.test.ts`, and +`apps/server/src/orchestration/decider.seenMarker.test.ts`. diff --git a/apps/mobile/src/features/threads/ThreadFeed.tsx b/apps/mobile/src/features/threads/ThreadFeed.tsx index 20848cd2ad103..59169006c8647 100644 --- a/apps/mobile/src/features/threads/ThreadFeed.tsx +++ b/apps/mobile/src/features/threads/ThreadFeed.tsx @@ -172,6 +172,7 @@ import { WORK_GROUP_TOGGLE_HEIGHT, } from "./thread-work-log"; import { appendPendingThreadMessages, type PendingThreadFeedEntry } from "./pending-thread-feed"; +import { seenMessagesFromFeed, useThreadSeenMarker } from "./useThreadSeenMarker"; import type { QueuedThreadMessage } from "../../state/thread-outbox-model"; import { useMarkdownCodeHighlight } from "./markdownCodeHighlightState"; import { @@ -2418,6 +2419,11 @@ export const ThreadFeed = memo(function ThreadFeed(props: ThreadFeedProps) { () => new Map(), [feedThreadKey], ); + const seenMessages = useMemo(() => seenMessagesFromFeed(props.feed), [props.feed]); + const handleViewableItemsChanged = useThreadSeenMarker({ + threadKey: feedThreadKey, + messages: seenMessages, + }); useEffect(() => { reportHeaderMaterialVisibility(false); @@ -2927,6 +2933,7 @@ export const ThreadFeed = memo(function ThreadFeed(props: ThreadFeedProps) { extraData={listAppearanceData} renderItem={renderItem} viewabilityConfig={THREAD_MEDIA_VIEWABILITY_CONFIG} + onViewableItemsChanged={handleViewableItemsChanged} keyExtractor={(entry) => entry.id} getItemType={(entry) => entry.type === "message" ? `message:${entry.message.role}` : entry.type diff --git a/apps/mobile/src/features/threads/useThreadSeenMarker.test.ts b/apps/mobile/src/features/threads/useThreadSeenMarker.test.ts new file mode 100644 index 0000000000000..26b74050a4a96 --- /dev/null +++ b/apps/mobile/src/features/threads/useThreadSeenMarker.test.ts @@ -0,0 +1,162 @@ +import { MessageId } from "@t3tools/contracts"; +import { buildSeenMarker, resetSeenMarkersForTest } from "@t3tools/client-runtime/seen-marker"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test"; + +const reactState = vi.hoisted(() => ({ + refs: [] as Array<{ current: unknown }>, + cursor: 0, + cleanups: [] as Array<() => void>, + focused: true, + appState: "active", + appListener: null as null | ((state: string) => void), +})); + +vi.mock("react", () => ({ + useRef: (initial: unknown) => { + const index = reactState.cursor; + reactState.cursor += 1; + const existing = reactState.refs[index]; + if (existing) return existing; + const ref = { current: initial }; + reactState.refs[index] = ref; + return ref; + }, + useEffect: (effect: () => void | (() => void)) => { + const cleanup = effect(); + if (typeof cleanup === "function") reactState.cleanups.push(cleanup); + }, + useEffectEvent: unknown>(callback: T) => callback, + useCallback: unknown>(callback: T) => callback, +})); + +vi.mock("@react-navigation/native", () => ({ + useIsFocused: () => reactState.focused, +})); + +vi.mock("react-native", () => ({ + AppState: { + get currentState() { + return reactState.appState; + }, + addEventListener: (_type: string, listener: (state: string) => void) => { + reactState.appListener = listener; + return { + remove: () => { + reactState.appListener = null; + }, + }; + }, + }, +})); + +import type { ThreadFeedEntry } from "../../lib/threadActivity"; +import { seenMessagesFromFeed, useThreadSeenMarker, viewableMessageIds } from "./useThreadSeenMarker"; + +const userId = MessageId.make("message-user"); +const assistantId = MessageId.make("message-assistant"); +const messages = [ + { id: userId, role: "user" }, + { id: assistantId, role: "assistant" }, +]; + +function feedMessage(id: MessageId, role: "user" | "assistant"): ThreadFeedEntry { + return { + type: "message", + id, + createdAt: "2026-11-20T03:00:00.000Z", + message: { + id, + role, + text: id, + turnId: null, + streaming: false, + createdAt: "2026-11-20T03:00:00.000Z", + updatedAt: "2026-11-20T03:00:00.000Z", + }, + } as ThreadFeedEntry; +} + +function renderTracker() { + reactState.cursor = 0; + reactState.cleanups = []; + return useThreadSeenMarker({ threadKey: "env:thread", messages }); +} + +function showAssistant(onViewable: ReturnType) { + onViewable({ + viewableItems: [ + { isViewable: true, item: feedMessage(userId, "user"), index: 0, key: userId }, + { isViewable: true, item: feedMessage(assistantId, "assistant"), index: 1, key: assistantId }, + ], + } as unknown as Parameters[0]); +} + +beforeEach(() => { + reactState.refs = []; + reactState.cursor = 0; + reactState.cleanups = []; + reactState.focused = true; + reactState.appState = "active"; + reactState.appListener = null; + resetSeenMarkersForTest(); + vi.useFakeTimers(); +}); + +afterEach(() => { + for (const cleanup of reactState.cleanups) cleanup(); + vi.useRealTimers(); +}); + +describe("mobile seen marker", () => { + it("marks a focused active screen after 2 seconds and not sooner", () => { + const onViewable = renderTracker(); + showAssistant(onViewable); + vi.advanceTimersByTime(1_999); + expect(buildSeenMarker("env:thread")).toBeUndefined(); + vi.advanceTimersByTime(1); + expect(buildSeenMarker("env:thread")?.lastSeenMessageId).toBe(assistantId); + }); + + it("does not count an unfocused screen or a background app", () => { + reactState.focused = false; + const blurred = renderTracker(); + showAssistant(blurred); + vi.advanceTimersByTime(2_000); + expect(buildSeenMarker("env:thread")).toBeUndefined(); + + reactState.refs = []; + reactState.focused = true; + reactState.appState = "background"; + const backgrounded = renderTracker(); + showAssistant(backgrounded); + vi.advanceTimersByTime(2_000); + expect(buildSeenMarker("env:thread")).toBeUndefined(); + }); + + it("cancels a dwell when the app leaves the foreground", () => { + const onViewable = renderTracker(); + showAssistant(onViewable); + vi.advanceTimersByTime(1_000); + reactState.appState = "background"; + reactState.appListener?.("background"); + vi.advanceTimersByTime(2_000); + expect(buildSeenMarker("env:thread")).toBeUndefined(); + }); + + it("reads message rows and skips everything else", () => { + const feed = [ + feedMessage(userId, "user"), + { type: "work-toggle", id: "toggle" } as ThreadFeedEntry, + feedMessage(assistantId, "assistant"), + ]; + expect(seenMessagesFromFeed(feed).map((message) => message.id)).toEqual([userId, assistantId]); + expect( + viewableMessageIds([ + { isViewable: false, item: feed[0]! }, + { isViewable: true, item: feed[1]! }, + { isViewable: true, item: feed[2]! }, + ]), + ).toEqual([assistantId]); + }); +}); + diff --git a/apps/mobile/src/features/threads/useThreadSeenMarker.ts b/apps/mobile/src/features/threads/useThreadSeenMarker.ts new file mode 100644 index 0000000000000..c72cdfdca54d1 --- /dev/null +++ b/apps/mobile/src/features/threads/useThreadSeenMarker.ts @@ -0,0 +1,74 @@ +import type { OnViewableItemsChangedInfo } from "@legendapp/list/react-native"; +import { + createSeenMarkerSession, + type SeenMarkerSession, + type SeenMessage, +} from "@t3tools/client-runtime/seen-marker"; +import type { MessageId } from "@t3tools/contracts"; +import { useIsFocused } from "@react-navigation/native"; +import { useCallback, useEffect, useEffectEvent, useRef } from "react"; +import { AppState } from "react-native"; + +import type { ThreadFeedEntry } from "../../lib/threadActivity"; + +export function seenMessagesFromFeed(feed: ReadonlyArray): SeenMessage[] { + const messages: SeenMessage[] = []; + for (const entry of feed) { + if (entry.type === "message") messages.push(entry.message); + } + return messages; +} + +export function viewableMessageIds( + viewableItems: ReadonlyArray<{ isViewable: boolean; item: ThreadFeedEntry }>, +): MessageId[] { + const ids: MessageId[] = []; + for (const token of viewableItems) { + if (token.isViewable && token.item.type === "message") ids.push(token.item.message.id); + } + return ids; +} + +export function useThreadSeenMarker(input: { + threadKey: string; + messages: ReadonlyArray; +}) { + const { threadKey, messages } = input; + const isFocused = useIsFocused(); + const sessionRef = useRef(null); + const visibleIdsRef = useRef>([]); + const getMessages = useEffectEvent(() => messages); + const isActive = useEffectEvent(() => isFocused && AppState.currentState === "active"); + + useEffect(() => { + visibleIdsRef.current = []; + const session = createSeenMarkerSession({ + threadKey, + getMessages, + seenAt: () => new Date().toISOString(), + timers: { + set: (callback, ms) => setTimeout(callback, ms), + clear: (handle) => clearTimeout(handle as ReturnType), + }, + }); + sessionRef.current = session; + session.update({ active: isActive(), visibleIds: visibleIdsRef.current }); + const subscription = AppState.addEventListener("change", () => + session.update({ active: isActive() }), + ); + return () => { + subscription.remove(); + session.dispose(); + sessionRef.current = null; + }; + }, [threadKey]); + + useEffect(() => { + sessionRef.current?.update({ active: isActive() }); + }, [isFocused, messages]); + + return useCallback((info: OnViewableItemsChangedInfo) => { + visibleIdsRef.current = viewableMessageIds(info.viewableItems); + sessionRef.current?.update({ visibleIds: visibleIdsRef.current }); + }, []); +} diff --git a/apps/mobile/src/state/use-thread-outbox-drain.ts b/apps/mobile/src/state/use-thread-outbox-drain.ts index 8a3a8513eb8d3..7ec19080b2963 100644 --- a/apps/mobile/src/state/use-thread-outbox-drain.ts +++ b/apps/mobile/src/state/use-thread-outbox-drain.ts @@ -17,6 +17,7 @@ import { AsyncResult } from "effect/unstable/reactivity"; import { useCallback, useEffect, useRef, useState } from "react"; import { Alert } from "react-native"; +import { buildSeenMarker } from "@t3tools/client-runtime/seen-marker"; import { scopedThreadKey } from "../lib/scopedEntities"; import { buildProjectThreadStartTurnInput } from "../lib/projectThreadStartTurn"; import { serializeComposerMessageForServer, uploadedComposerContext } from "../lib/composerContext"; @@ -800,6 +801,9 @@ export function useThreadOutboxDrain(): void { settings, currentConfig.providers, ); + const seenMarker = buildSeenMarker( + scopedThreadKey(queuedMessage.environmentId, queuedMessage.threadId), + ); const deliveryResult = await startTurn({ environmentId: queuedMessage.environmentId, input: { @@ -822,6 +826,7 @@ export function useThreadOutboxDrain(): void { modelSelection: sendSettings.modelSelection, runtimeMode: sendSettings.runtimeMode, interactionMode: sendSettings.interactionMode, + ...(seenMarker ? { seenMarker } : {}), createdAt: queuedMessage.createdAt, }, }); diff --git a/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts b/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts index 7d8ec755f2833..ca0ff93cbc020 100644 --- a/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts +++ b/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts @@ -21,6 +21,7 @@ import { } from "@t3tools/contracts"; import { assistantCitationsToPlainText } from "@t3tools/shared/assistantCitations"; import { projectComposerContextForProvider } from "@t3tools/shared/composerContextReferences"; +import { formatSeenMarkerForProvider } from "@t3tools/shared/seenMarker"; import { isTemporaryWorktreeBranch, WORKTREE_BRANCH_PREFIX } from "@t3tools/shared/git"; import * as Cache from "effect/Cache"; import * as Cause from "effect/Cause"; @@ -1625,10 +1626,13 @@ const make = Effect.gen(function* () { } const sendTurnRequest = yield* buildSendTurnRequestForThread({ threadId: event.payload.threadId, - messageText: projectComposerContextForProvider({ - text: message.text, - records: message.context?.records ?? [], - }), + messageText: formatSeenMarkerForProvider( + projectComposerContextForProvider({ + text: message.text, + records: message.context?.records ?? [], + }), + event.payload.seenMarker, + ), ...(message.attachments !== undefined ? { attachments: message.attachments } : {}), ...(event.payload.modelSelection !== undefined ? { modelSelection: event.payload.modelSelection } diff --git a/apps/server/src/orchestration/decider.seenMarker.test.ts b/apps/server/src/orchestration/decider.seenMarker.test.ts new file mode 100644 index 0000000000000..c8e3e64e77c56 --- /dev/null +++ b/apps/server/src/orchestration/decider.seenMarker.test.ts @@ -0,0 +1,171 @@ +import { + CommandId, + MessageId, + ProjectId, + ProviderInstanceId, + ThreadId, + type OrchestrationReadModel, + type OrchestrationThread, +} from "@t3tools/contracts"; +import { formatSeenMarkerForProvider } from "@t3tools/shared/seenMarker"; +import * as NodeServices from "@effect/platform-node/NodeServices"; +import { expect, it } from "@effect/vitest"; +import * as Effect from "effect/Effect"; + +import { decideOrchestrationCommand } from "./decider.ts"; + +const NOW = "2026-11-20T03:00:00.000Z"; + +function message(id: string, role: "user" | "assistant"): OrchestrationThread["messages"][number] { + return { + id: MessageId.make(id), + role, + text: id, + turnId: null, + streaming: false, + createdAt: NOW, + updatedAt: NOW, + } as OrchestrationThread["messages"][number]; +} + +function makeReadModel( + messages: ReadonlyArray, +): OrchestrationReadModel { + return { + snapshotSequence: 0, + projects: [], + threads: [ + { + id: ThreadId.make("thread-1"), + projectId: ProjectId.make("project-1"), + title: "Thread", + modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5.4" }, + runtimeMode: "full-access", + interactionMode: "default", + branch: null, + worktreePath: null, + pullRequests: [], + latestTurn: null, + createdAt: NOW, + updatedAt: NOW, + archivedAt: null, + settledOverride: null, + settledAt: null, + snoozedUntil: null, + snoozedAt: null, + deletedAt: null, + messages: [...messages], + proposedPlans: [], + activities: [], + checkpoints: [], + session: null, + }, + ], + updatedAt: NOW, + }; +} + +function turnStart(seenMarker?: { + lastSeenMessageId: ReturnType; + seenAt: string; +}) { + return { + type: "thread.turn.start" as const, + commandId: CommandId.make("cmd-turn"), + threadId: ThreadId.make("thread-1"), + message: { + messageId: MessageId.make("message-next"), + role: "user" as const, + text: "What did I miss?", + attachments: [], + }, + runtimeMode: "full-access" as const, + interactionMode: "default" as const, + ...(seenMarker ? { seenMarker } : {}), + createdAt: NOW, + }; +} + +it.layer(NodeServices.layer)("seen marker decider", (it) => { + it.effect("a send with no marker, including an MCP send, adds no catch-up", () => + Effect.gen(function* () { + const result = yield* decideOrchestrationCommand({ + command: turnStart(), + readModel: makeReadModel([ + message("message-user", "user"), + message("message-assistant", "assistant"), + ]), + }); + const events = Array.isArray(result) ? result : [result]; + const start = events.find((event) => event.type === "thread.turn-start-requested"); + expect(start?.type).toBe("thread.turn-start-requested"); + if (start?.type !== "thread.turn-start-requested") return; + expect(start.payload.seenMarker).toBeUndefined(); + expect(formatSeenMarkerForProvider("What did I miss?", start.payload.seenMarker)).toBe( + "What did I miss?", + ); + }), + ); + + it.effect("counts unseen assistant messages onto the turn the founder sends", () => + Effect.gen(function* () { + const result = yield* decideOrchestrationCommand({ + command: turnStart({ + lastSeenMessageId: MessageId.make("message-user"), + seenAt: NOW, + }), + readModel: makeReadModel([ + message("message-user", "user"), + message("message-assistant-1", "assistant"), + message("message-user-2", "user"), + message("message-assistant-2", "assistant"), + ]), + }); + const events = Array.isArray(result) ? result : [result]; + const start = events.find((event) => event.type === "thread.turn-start-requested"); + if (start?.type !== "thread.turn-start-requested") { + expect(start?.type).toBe("thread.turn-start-requested"); + return; + } + expect(start.payload.seenMarker).toEqual({ + lastSeenMessageId: MessageId.make("message-user"), + seenAt: NOW, + unseenCount: 2, + }); + expect(formatSeenMarkerForProvider("What did I miss?", start.payload.seenMarker)).toContain( + "The user last saw message message-user; 2 messages since are unseen.", + ); + }), + ); + + it.effect("drops a marker the thread cannot summarize", () => + Effect.gen(function* () { + const missing = yield* decideOrchestrationCommand({ + command: turnStart({ + lastSeenMessageId: MessageId.make("missing"), + seenAt: NOW, + }), + readModel: makeReadModel([message("message-assistant", "assistant")]), + }); + const caughtUp = yield* decideOrchestrationCommand({ + command: turnStart({ + lastSeenMessageId: MessageId.make("message-assistant"), + seenAt: NOW, + }), + readModel: makeReadModel([ + message("message-user", "user"), + message("message-assistant", "assistant"), + ]), + }); + for (const result of [missing, caughtUp]) { + const events = Array.isArray(result) ? result : [result]; + const start = events.find((event) => event.type === "thread.turn-start-requested"); + if (start?.type !== "thread.turn-start-requested") { + expect(start?.type).toBe("thread.turn-start-requested"); + return; + } + expect(start.payload.seenMarker).toBeUndefined(); + } + }), + ); +}); diff --git a/apps/server/src/orchestration/decider.ts b/apps/server/src/orchestration/decider.ts index db8796de67fe2..752b456124af4 100644 --- a/apps/server/src/orchestration/decider.ts +++ b/apps/server/src/orchestration/decider.ts @@ -21,6 +21,7 @@ import { threadPullRequestKeysEqual, } from "@t3tools/shared/threadPullRequests"; import { compareDateTimeStrings } from "@t3tools/shared/dateTime"; +import { summarizeSeenMarker } from "@t3tools/shared/seenMarker"; import * as DateTime from "effect/DateTime"; import * as Crypto from "effect/Crypto"; import * as Effect from "effect/Effect"; @@ -1436,6 +1437,7 @@ export const decideOrchestrationCommand = Effect.fn("decideOrchestrationCommand" updatedAt: command.createdAt, }, }; + const seenMarker = summarizeSeenMarker(command.seenMarker, targetThread.messages); const turnStartRequestedEvent: Omit = { ...(yield* withEventBase({ aggregateKind: "thread", @@ -1456,6 +1458,7 @@ export const decideOrchestrationCommand = Effect.fn("decideOrchestrationCommand" runtimeMode: targetThread.runtimeMode, interactionMode: targetThread.interactionMode, ...(sourceProposedPlan !== undefined ? { sourceProposedPlan } : {}), + ...(seenMarker !== undefined ? { seenMarker } : {}), createdAt: command.createdAt, }, }; diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx index d906892913150..16125b5e2af30 100644 --- a/apps/web/src/components/ChatView.tsx +++ b/apps/web/src/components/ChatView.tsx @@ -65,6 +65,7 @@ import { scopeProjectRef, scopeThreadRef, } from "@t3tools/client-runtime/environment"; +import { buildSeenMarker, type SeenMessage } from "@t3tools/client-runtime/seen-marker"; import { applyClaudePromptEffortPrefix, createModelSelection, @@ -338,6 +339,7 @@ import { type ReviewCommentContext } from "../reviewCommentContext"; import { environmentCatalog } from "../connection/catalog"; import { isDesktopLocalConnectionTarget } from "../connection/desktopLocal"; import { useEnvironmentDisconnectDelay } from "../hooks/useEnvironmentDisconnectDelay"; +import { useSeenMarkerTracking } from "../hooks/useSeenMarkerTracking"; import { selectThreadTerminalUiState, useTerminalUiStateStore } from "../terminalUiStateStore"; import { useKnownTerminalSessions, useThreadRunningTerminalIds } from "../state/terminalSessions"; import { resolvePostStartObservationReceipt } from "@t3tools/client-runtime/state/post-start-observation-receipt"; @@ -539,6 +541,12 @@ import { } from "./chat/composerPromptHistory"; const EMPTY_ACTIVITIES: OrchestrationThreadActivity[] = []; +const EMPTY_SEEN_MESSAGES: ReadonlyArray = []; + +function seenMarkerForSend(environmentId: EnvironmentId, threadId: ThreadId) { + const seenMarker = buildSeenMarker(scopedThreadKey(scopeThreadRef(environmentId, threadId))); + return seenMarker ? { seenMarker } : {}; +} const EMPTY_QUEUED_MESSAGES: QueuedComposerMessage[] = []; const EMPTY_PROVIDERS: ServerProvider[] = []; const EMPTY_USAGE_LIMIT_SOURCES: UsageLimitSourceSnapshots = []; @@ -3599,6 +3607,11 @@ export default function ChatView(props: ChatViewProps) { displayedTimeline.displayThreadKey, activeThreadKey, ); + useSeenMarkerTracking({ + threadKey: isServerThread && !paintOnlyDisplayedTimeline ? activeThreadKey : null, + getScrollNode: () => legendListRef.current?.getScrollableNode() ?? null, + messages: activeServerThread?.messages ?? EMPTY_SEEN_MESSAGES, + }); const displayedThreadRef = parseScopedThreadKey(displayedTimelineKey); // Live stages of a bootstrap worktree setup. A worktree send creates the // server thread under the route's thread id before anything else, so the @@ -7233,6 +7246,7 @@ export default function ChatView(props: ChatViewProps) { modelSelection: context.selectedModelSelection, runtimeMode, interactionMode: context.interactionMode, + ...seenMarkerForSend(activeThread.environmentId, threadId), createdAt, }, }); @@ -8487,6 +8501,7 @@ export default function ChatView(props: ChatViewProps) { runtimeMode, interactionMode: sendInteractionMode, ...(bootstrap ? { bootstrap } : {}), + ...seenMarkerForSend(activeThread.environmentId, threadIdForSend), createdAt: messageCreatedAt, }, }); @@ -9112,6 +9127,7 @@ export default function ChatView(props: ChatViewProps) { titleSeed: activeThread.title, runtimeMode, interactionMode: nextInteractionMode, + ...seenMarkerForSend(activeThread.environmentId, threadIdForSend), ...(nextInteractionMode === "default" && activeProposedPlan ? { sourceProposedPlan: { diff --git a/apps/web/src/hooks/useSeenMarkerTracking.test.ts b/apps/web/src/hooks/useSeenMarkerTracking.test.ts new file mode 100644 index 0000000000000..cc36ea4fa150c --- /dev/null +++ b/apps/web/src/hooks/useSeenMarkerTracking.test.ts @@ -0,0 +1,212 @@ +import { MessageId } from "@t3tools/contracts"; +import { + buildSeenMarker, + resetSeenMarkersForTest, + type SeenTimers, +} from "@t3tools/client-runtime/seen-marker"; +import { beforeEach, describe, expect, it, vi } from "vite-plus/test"; + +import { + startSeenMarkerSampling, + visibleMessageIds, + type SeenScrollNode, +} from "./useSeenMarkerTracking"; + +const seenAt = "2026-11-20T03:00:00.000Z"; +const userId = MessageId.make("message-user"); +const assistantId = MessageId.make("message-assistant"); +const messages = [ + { id: userId, role: "user" }, + { id: assistantId, role: "assistant" }, +]; + +function manualTimers() { + let nextId = 1; + const pending = new Map void>(); + const timers: SeenTimers = { + set(callback) { + const id = nextId; + nextId += 1; + pending.set(id, callback); + return id; + }, + clear(handle) { + pending.delete(handle as number); + }, + }; + return { + timers, + pendingCount: () => pending.size, + fireNext() { + const next = pending.entries().next().value; + if (!next) throw new Error("no dwell timer"); + pending.delete(next[0]); + next[1](); + }, + }; +} + +function scrollNode(): SeenScrollNode { + return { + getBoundingClientRect: () => ({ top: 0, bottom: 400 }), + querySelectorAll: () => [ + { + getBoundingClientRect: () => ({ top: 10, bottom: 80 }), + getAttribute: (name: string) => (name === "data-message-id" ? userId : null), + }, + { + getBoundingClientRect: () => ({ top: 90, bottom: 200 }), + getAttribute: (name: string) => (name === "data-message-id" ? assistantId : null), + }, + { + getBoundingClientRect: () => ({ top: 500, bottom: 600 }), + getAttribute: () => MessageId.make("message-below"), + }, + ], + }; +} + +function host() { + const state = { visibility: "visible" as DocumentVisibilityState, focused: true }; + const listeners = new Map void>>(); + const frames: Array<() => void> = []; + const add = (key: string, listener: EventListenerOrEventListenerObject) => { + const list = listeners.get(key) ?? []; + list.push(listener as () => void); + listeners.set(key, list); + }; + const remove = (key: string, listener: EventListenerOrEventListenerObject) => { + listeners.set( + key, + (listeners.get(key) ?? []).filter((entry) => entry !== listener), + ); + }; + return { + state, + frames, + emit(key: string) { + for (const listener of listeners.get(key) ?? []) listener(); + }, + flush() { + const queued = frames.splice(0); + for (const frame of queued) frame(); + }, + samplingHost: { + window: { + addEventListener: (type: string, listener: EventListenerOrEventListenerObject) => + add(`win:${type}`, listener), + removeEventListener: (type: string, listener: EventListenerOrEventListenerObject) => + remove(`win:${type}`, listener), + requestAnimationFrame: (callback: () => void) => { + frames.push(callback); + return frames.length; + }, + cancelAnimationFrame: () => {}, + }, + document: { + addEventListener: (type: string, listener: EventListenerOrEventListenerObject) => + add(`doc:${type}`, listener), + removeEventListener: (type: string, listener: EventListenerOrEventListenerObject) => + remove(`doc:${type}`, listener), + hasFocus: () => state.focused, + get visibilityState() { + return state.visibility; + }, + }, + }, + }; +} + +beforeEach(() => { + resetSeenMarkersForTest(); +}); + +describe("timeline seen sampling", () => { + it("scroll and a 2 second dwell update local state only", () => { + const fetchSpy = vi.fn(); + const socketSpy = vi.fn(); + vi.stubGlobal("fetch", fetchSpy); + vi.stubGlobal("WebSocket", socketSpy); + const clock = manualTimers(); + const page = host(); + const sampling = startSeenMarkerSampling({ + host: page.samplingHost, + threadKey: "env:thread", + getScrollNode: scrollNode, + getMessages: () => messages, + now: () => new Date(seenAt), + timers: clock.timers, + }); + page.flush(); + expect(buildSeenMarker("env:thread")).toBeUndefined(); + page.emit("doc:scroll"); + page.flush(); + expect(clock.pendingCount()).toBe(1); + expect(fetchSpy).not.toHaveBeenCalled(); + expect(socketSpy).not.toHaveBeenCalled(); + clock.fireNext(); + expect(buildSeenMarker("env:thread")).toEqual({ + lastSeenMessageId: assistantId, + seenAt, + }); + expect(fetchSpy).not.toHaveBeenCalled(); + expect(socketSpy).not.toHaveBeenCalled(); + expect(Object.keys(sampling).sort()).toEqual(["dispose", "requestSample"]); + sampling.dispose(); + vi.unstubAllGlobals(); + }); + + it("does not mark a hidden or blurred window", () => { + const clock = manualTimers(); + const page = host(); + page.state.visibility = "hidden"; + page.state.focused = false; + const sampling = startSeenMarkerSampling({ + host: page.samplingHost, + threadKey: "env:thread", + getScrollNode: scrollNode, + getMessages: () => messages, + now: () => new Date(seenAt), + timers: clock.timers, + }); + page.flush(); + page.emit("doc:scroll"); + page.flush(); + expect(clock.pendingCount()).toBe(0); + expect(buildSeenMarker("env:thread")).toBeUndefined(); + sampling.dispose(); + }); + + it("cancels a dwell when the window blurs", () => { + const clock = manualTimers(); + const page = host(); + const sampling = startSeenMarkerSampling({ + host: page.samplingHost, + threadKey: "env:thread", + getScrollNode: scrollNode, + getMessages: () => messages, + now: () => new Date(seenAt), + timers: clock.timers, + }); + page.flush(); + expect(clock.pendingCount()).toBe(1); + page.state.focused = false; + page.emit("win:blur"); + expect(page.frames).toEqual([]); + expect(clock.pendingCount()).toBe(0); + expect(buildSeenMarker("env:thread")).toBeUndefined(); + page.state.focused = true; + page.emit("win:focus"); + expect(page.frames).toEqual([]); + expect(clock.pendingCount()).toBe(1); + page.state.visibility = "hidden"; + page.emit("doc:visibilitychange"); + expect(page.frames).toEqual([]); + expect(clock.pendingCount()).toBe(0); + sampling.dispose(); + }); + + it("ignores rows outside the viewport", () => { + expect(visibleMessageIds(scrollNode())).toEqual([userId, assistantId]); + }); +}); diff --git a/apps/web/src/hooks/useSeenMarkerTracking.ts b/apps/web/src/hooks/useSeenMarkerTracking.ts new file mode 100644 index 0000000000000..8d8d19cb5f955 --- /dev/null +++ b/apps/web/src/hooks/useSeenMarkerTracking.ts @@ -0,0 +1,133 @@ +import type { MessageId } from "@t3tools/contracts"; +import { + createSeenMarkerSession, + type SeenMessage, + type SeenTimers, +} from "@t3tools/client-runtime/seen-marker"; +import { useEffect, useEffectEvent, useRef } from "react"; + +interface SeenRect { + top: number; + bottom: number; +} + +export interface SeenSamplingHost { + window: Pick & { + requestAnimationFrame(callback: () => void): number; + cancelAnimationFrame(handle: number): void; + }; + document: Pick & { + readonly visibilityState: DocumentVisibilityState; + }; +} + +export interface SeenScrollNode { + getBoundingClientRect(): SeenRect; + querySelectorAll(selector: string): Iterable<{ + getBoundingClientRect(): SeenRect; + getAttribute(name: string): string | null; + }>; +} + +export function visibleMessageIds(node: SeenScrollNode): MessageId[] { + const viewport = node.getBoundingClientRect(); + const ids: MessageId[] = []; + for (const element of node.querySelectorAll("[data-message-id]")) { + const id = element.getAttribute("data-message-id"); + if (!id) continue; + const rect = element.getBoundingClientRect(); + if (rect.bottom > viewport.top && rect.top < viewport.bottom) ids.push(id as MessageId); + } + return ids; +} + +export function startSeenMarkerSampling(input: { + host: SeenSamplingHost; + threadKey: string; + getScrollNode: () => SeenScrollNode | null | undefined; + getMessages: () => ReadonlyArray; + now?: () => Date; + timers?: SeenTimers; +}) { + const { window: win, document: doc } = input.host; + const session = createSeenMarkerSession({ + threadKey: input.threadKey, + getMessages: input.getMessages, + seenAt: () => (input.now ?? (() => new Date()))().toISOString(), + timers: input.timers ?? { + set: (callback, ms) => setTimeout(callback, ms), + clear: (handle) => clearTimeout(handle as ReturnType), + }, + }); + let frame: number | null = null; + + const sample = () => { + const node = input.getScrollNode(); + const active = doc.visibilityState === "visible" && doc.hasFocus(); + session.update({ active, visibleIds: active && node ? visibleMessageIds(node) : [] }); + }; + const requestSample = () => { + if (frame !== null) return; + frame = win.requestAnimationFrame(() => { + frame = null; + sample(); + }); + }; + const sampleNow = () => { + if (frame !== null) win.cancelAnimationFrame(frame); + frame = null; + sample(); + }; + const scrollOptions = { capture: true, passive: true } as const; + + doc.addEventListener("scroll", requestSample, scrollOptions); + doc.addEventListener("visibilitychange", sampleNow); + win.addEventListener("focus", sampleNow); + win.addEventListener("blur", sampleNow); + win.addEventListener("resize", requestSample); + requestSample(); + + return { + requestSample, + dispose() { + if (frame !== null) win.cancelAnimationFrame(frame); + frame = null; + session.dispose(); + doc.removeEventListener("scroll", requestSample, scrollOptions); + doc.removeEventListener("visibilitychange", sampleNow); + win.removeEventListener("focus", sampleNow); + win.removeEventListener("blur", sampleNow); + win.removeEventListener("resize", requestSample); + }, + }; +} + +export function useSeenMarkerTracking(input: { + threadKey: string | null; + getScrollNode: () => SeenScrollNode | null | undefined; + messages: ReadonlyArray; +}) { + const { threadKey, messages } = input; + const getScrollNode = useEffectEvent(() => input.getScrollNode()); + const getMessages = useEffectEvent(() => messages); + const samplingRef = useRef | null>(null); + + useEffect(() => { + if (threadKey === null) return; + const sampling = startSeenMarkerSampling({ + host: { window, document }, + threadKey, + getScrollNode, + getMessages, + }); + samplingRef.current = sampling; + return () => { + sampling.dispose(); + samplingRef.current = null; + }; + }, [threadKey]); + + useEffect(() => { + samplingRef.current?.requestSample(); + }, [messages]); +} diff --git a/packages/client-runtime/package.json b/packages/client-runtime/package.json index ed024846605f5..04b396deb3843 100644 --- a/packages/client-runtime/package.json +++ b/packages/client-runtime/package.json @@ -3,6 +3,10 @@ "private": true, "type": "module", "exports": { + "./seen-marker": { + "types": "./src/seenMarker.ts", + "default": "./src/seenMarker.ts" + }, "./device/stream": { "types": "./src/device/stream.ts", "default": "./src/device/stream.ts" diff --git a/packages/client-runtime/src/seenMarker.test.ts b/packages/client-runtime/src/seenMarker.test.ts new file mode 100644 index 0000000000000..17334d0da6ac4 --- /dev/null +++ b/packages/client-runtime/src/seenMarker.test.ts @@ -0,0 +1,127 @@ +import { MessageId } from "@t3tools/contracts"; +import { beforeEach, describe, expect, it } from "vite-plus/test"; + +import { + buildSeenMarker, + createSeenMarkerSession, + pickNewestMessageId, + resetSeenMarkersForTest, + type SeenTimers, +} from "./seenMarker.ts"; + +const seenAt = "2026-11-20T03:00:00.000Z"; +const userId = MessageId.make("message-user"); +const assistantId = MessageId.make("message-assistant"); +const laterId = MessageId.make("message-later"); +const messages = [ + { id: userId, role: "user" }, + { id: assistantId, role: "assistant" }, + { id: laterId, role: "assistant" }, +]; + +function manualTimers() { + let nextId = 1; + const pending = new Map void; ms: number }>(); + const timers: SeenTimers = { + set(callback, ms) { + const id = nextId; + nextId += 1; + pending.set(id, { callback, ms }); + return id; + }, + clear(handle) { + pending.delete(handle as number); + }, + }; + return { + timers, + pendingMs: () => [...pending.values()].map((entry) => entry.ms), + fireNext() { + const next = pending.entries().next().value; + if (!next) throw new Error("no dwell timer"); + pending.delete(next[0]); + next[1].callback(); + }, + }; +} + +function session(clock: ReturnType) { + return createSeenMarkerSession({ + threadKey: "env:thread", + getMessages: () => messages, + seenAt: () => seenAt, + timers: clock.timers, + }); +} + +beforeEach(() => { + resetSeenMarkersForTest(); +}); + +describe("seen dwell", () => { + it("marks the newest visible message after 2 seconds and not before", () => { + const clock = manualTimers(); + const tracker = session(clock); + tracker.update({ active: true, visibleIds: [userId, assistantId] }); + expect(clock.pendingMs()).toEqual([2_000]); + expect(buildSeenMarker("env:thread")).toBeUndefined(); + clock.fireNext(); + expect(buildSeenMarker("env:thread")).toEqual({ + lastSeenMessageId: assistantId, + seenAt, + }); + tracker.dispose(); + }); + + it("does not count a hidden or unfocused window", () => { + const clock = manualTimers(); + const tracker = session(clock); + tracker.update({ active: false, visibleIds: [assistantId] }); + expect(clock.pendingMs()).toEqual([]); + expect(buildSeenMarker("env:thread")).toBeUndefined(); + + tracker.update({ active: true, visibleIds: [assistantId] }); + expect(clock.pendingMs()).toEqual([2_000]); + tracker.update({ active: false, visibleIds: [assistantId] }); + expect(clock.pendingMs()).toEqual([]); + expect(buildSeenMarker("env:thread")).toBeUndefined(); + tracker.dispose(); + }); + + it("only moves forward", () => { + const clock = manualTimers(); + const tracker = session(clock); + tracker.update({ active: true, visibleIds: [laterId] }); + clock.fireNext(); + tracker.update({ active: true, visibleIds: [assistantId] }); + clock.fireNext(); + expect(buildSeenMarker("env:thread")?.lastSeenMessageId).toBe(laterId); + tracker.dispose(); + }); + + it("does not record a view when messages are only read", () => { + expect(pickNewestMessageId([userId, assistantId], messages)).toBe(assistantId); + expect(buildSeenMarker("env:thread")).toBeUndefined(); + }); + + it("does not mark a message that is still streaming", () => { + const streamingId = MessageId.make("message-streaming"); + const withStreaming = [...messages, { id: streamingId, role: "assistant", streaming: true }]; + expect(pickNewestMessageId([assistantId, streamingId], withStreaming)).toBe(assistantId); + expect(pickNewestMessageId([streamingId], withStreaming)).toBeNull(); + + const clock = manualTimers(); + const tracker = createSeenMarkerSession({ + threadKey: "env:thread", + getMessages: () => withStreaming, + seenAt: () => seenAt, + timers: clock.timers, + }); + tracker.update({ active: true, visibleIds: [streamingId] }); + expect(clock.pendingMs()).toEqual([]); + tracker.update({ active: true, visibleIds: [assistantId, streamingId] }); + clock.fireNext(); + expect(buildSeenMarker("env:thread")?.lastSeenMessageId).toBe(assistantId); + tracker.dispose(); + }); +}); diff --git a/packages/client-runtime/src/seenMarker.ts b/packages/client-runtime/src/seenMarker.ts new file mode 100644 index 0000000000000..74e101b60b53c --- /dev/null +++ b/packages/client-runtime/src/seenMarker.ts @@ -0,0 +1,145 @@ +import type { MessageId, ThreadSeenMarker } from "@t3tools/contracts"; + +export const SEEN_DWELL_MS = 2_000; + +export interface SeenSample { + active: boolean; + newestVisibleMessageId: MessageId | null; +} + +export interface SeenDwellTracker { + observe(sample: SeenSample): void; + dispose(): void; +} + +export interface SeenTimers { + set(callback: () => void, ms: number): unknown; + clear(handle: unknown): void; +} + +export function createSeenDwellTracker(options: { + onSeen: (messageId: MessageId) => void; + dwellMs?: number; + timers: SeenTimers; +}): SeenDwellTracker { + const timers = options.timers; + const dwellMs = options.dwellMs ?? SEEN_DWELL_MS; + let pendingId: MessageId | null = null; + let handle: unknown = null; + + const cancel = () => { + if (handle !== null) timers.clear(handle); + handle = null; + pendingId = null; + }; + + return { + observe(sample) { + const candidate = sample.active ? sample.newestVisibleMessageId : null; + if (candidate === pendingId) return; + cancel(); + if (candidate === null) return; + pendingId = candidate; + handle = timers.set(() => { + handle = null; + pendingId = null; + options.onSeen(candidate); + }, dwellMs); + }, + dispose: cancel, + }; +} + +export interface SeenMessage { + id: MessageId; + role: string; + streaming?: boolean; +} + +interface SeenEntry { + messageId: MessageId; + seenAt: string; +} + +const seenByThreadKey = new Map(); + +export function recordSeenMessage(input: { + threadKey: string; + messageId: MessageId; + messages: ReadonlyArray; + seenAt: string; +}): boolean { + const nextIndex = input.messages.findIndex((message) => message.id === input.messageId); + if (nextIndex < 0 || input.messages[nextIndex]?.streaming === true) return false; + const previous = seenByThreadKey.get(input.threadKey); + if (previous) { + const previousIndex = input.messages.findIndex((message) => message.id === previous.messageId); + if (previousIndex >= nextIndex) return false; + } + seenByThreadKey.set(input.threadKey, { messageId: input.messageId, seenAt: input.seenAt }); + return true; +} + +export function pickNewestMessageId( + visibleIds: Iterable, + messages: ReadonlyArray, +): MessageId | null { + const visible = new Set(visibleIds); + for (let index = messages.length - 1; index >= 0; index -= 1) { + const message = messages[index]!; + if (message.streaming === true) continue; + if (visible.has(message.id)) return message.id; + } + return null; +} + +export function buildSeenMarker(threadKey: string): ThreadSeenMarker | undefined { + const seen = seenByThreadKey.get(threadKey); + if (!seen) return undefined; + return { lastSeenMessageId: seen.messageId, seenAt: seen.seenAt }; +} + +export interface SeenMarkerSession { + update(input: { active?: boolean; visibleIds?: Iterable }): void; + dispose(): void; +} + +export function createSeenMarkerSession(input: { + threadKey: string; + getMessages: () => ReadonlyArray; + seenAt: () => string; + timers: SeenTimers; + dwellMs?: number; +}): SeenMarkerSession { + const tracker = createSeenDwellTracker({ + onSeen: (messageId) => + recordSeenMessage({ + threadKey: input.threadKey, + messageId, + messages: input.getMessages(), + seenAt: input.seenAt(), + }), + timers: input.timers, + ...(input.dwellMs !== undefined ? { dwellMs: input.dwellMs } : {}), + }); + let active = false; + let visibleIds: ReadonlyArray = []; + + return { + update(next) { + if (next.active !== undefined) active = next.active; + if (next.visibleIds !== undefined) visibleIds = [...next.visibleIds]; + tracker.observe({ + active, + newestVisibleMessageId: active + ? pickNewestMessageId(visibleIds, input.getMessages()) + : null, + }); + }, + dispose: tracker.dispose, + }; +} + +export function resetSeenMarkersForTest() { + seenByThreadKey.clear(); +} diff --git a/packages/contracts/src/orchestration.ts b/packages/contracts/src/orchestration.ts index 9a82c5599f0ee..de1a12f6df8ae 100644 --- a/packages/contracts/src/orchestration.ts +++ b/packages/contracts/src/orchestration.ts @@ -1367,6 +1367,19 @@ export const ThreadTurnStartRouteBinding = Schema.Struct({ interactionMode: ProviderInteractionMode, }); +export const ThreadSeenMarker = Schema.Struct({ + lastSeenMessageId: MessageId, + seenAt: IsoDateTime, +}); +export type ThreadSeenMarker = typeof ThreadSeenMarker.Type; + +export const ThreadSeenMarkerSummary = Schema.Struct({ + lastSeenMessageId: MessageId, + seenAt: IsoDateTime, + unseenCount: NonNegativeInt, +}); +export type ThreadSeenMarkerSummary = typeof ThreadSeenMarkerSummary.Type; + export const ThreadTurnStartCommand = Schema.Struct({ type: Schema.Literal("thread.turn.start"), commandId: CommandId, @@ -1388,6 +1401,7 @@ export const ThreadTurnStartCommand = Schema.Struct({ ), bootstrap: Schema.optional(ThreadTurnStartBootstrap), sourceProposedPlan: Schema.optional(SourceProposedPlanReference), + seenMarker: Schema.optional(ThreadSeenMarker), createdAt: IsoDateTime, }); @@ -1410,6 +1424,7 @@ const ClientThreadTurnStartCommand = Schema.Struct({ interactionMode: ProviderInteractionMode, bootstrap: Schema.optional(ThreadTurnStartBootstrap), sourceProposedPlan: Schema.optional(SourceProposedPlanReference), + seenMarker: Schema.optional(ThreadSeenMarker), createdAt: IsoDateTime, }); @@ -1980,6 +1995,7 @@ export const ThreadTurnStartRequestedPayload = Schema.Struct({ Schema.withDecodingDefault(Effect.succeed(DEFAULT_PROVIDER_INTERACTION_MODE)), ), sourceProposedPlan: Schema.optional(SourceProposedPlanReference), + seenMarker: Schema.optional(ThreadSeenMarkerSummary), createdAt: IsoDateTime, }); diff --git a/packages/shared/package.json b/packages/shared/package.json index 5bf88f3438aa2..cb6f0593b3c4f 100644 --- a/packages/shared/package.json +++ b/packages/shared/package.json @@ -3,6 +3,10 @@ "private": true, "type": "module", "exports": { + "./seenMarker": { + "types": "./src/seenMarker.ts", + "import": "./src/seenMarker.ts" + }, "./legacyCliLauncher": { "types": "./src/legacyCliLauncher.ts", "import": "./src/legacyCliLauncher.ts" diff --git a/packages/shared/src/seenMarker.test.ts b/packages/shared/src/seenMarker.test.ts new file mode 100644 index 0000000000000..f835e27142428 --- /dev/null +++ b/packages/shared/src/seenMarker.test.ts @@ -0,0 +1,90 @@ +import { MessageId } from "@t3tools/contracts"; +import { describe, expect, it } from "@effect/vitest"; + +import { formatSeenMarkerForProvider, summarizeSeenMarker } from "./seenMarker.ts"; + +const seenAt = "2026-11-20T03:00:00.000Z"; +const messages = [ + { id: MessageId.make("message-user-1"), role: "user" }, + { id: MessageId.make("message-assistant-1"), role: "assistant" }, + { id: MessageId.make("message-user-2"), role: "user" }, + { id: MessageId.make("message-assistant-2"), role: "assistant" }, +]; + +describe("summarizeSeenMarker", () => { + it("counts assistant messages after the one a person saw", () => { + expect( + summarizeSeenMarker( + { lastSeenMessageId: MessageId.make("message-user-1"), seenAt }, + messages, + ), + ).toEqual({ + lastSeenMessageId: MessageId.make("message-user-1"), + seenAt, + unseenCount: 2, + }); + }); + + it("ignores user messages and messages already seen", () => { + expect( + summarizeSeenMarker( + { lastSeenMessageId: MessageId.make("message-assistant-1"), seenAt }, + messages, + ), + ).toEqual({ + lastSeenMessageId: MessageId.make("message-assistant-1"), + seenAt, + unseenCount: 1, + }); + }); + + it("omits the marker when the id is missing or nothing is unseen", () => { + expect( + summarizeSeenMarker({ lastSeenMessageId: MessageId.make("missing"), seenAt }, messages), + ).toBeUndefined(); + expect( + summarizeSeenMarker( + { lastSeenMessageId: MessageId.make("message-assistant-2"), seenAt }, + messages, + ), + ).toBeUndefined(); + expect(summarizeSeenMarker(undefined, messages)).toBeUndefined(); + }); +}); + +describe("formatSeenMarkerForProvider", () => { + it("puts the catch-up line ahead of the founder's text", () => { + const text = formatSeenMarkerForProvider("Ship the fix", { + lastSeenMessageId: MessageId.make("message-user-1"), + seenAt, + unseenCount: 1, + }); + expect(text).toBe( + [ + '', + "The user last saw message message-user-1; 1 message since are unseen. Open the reply with a short catch-up on only those.", + "", + "", + "Ship the fix", + ].join("\n"), + ); + }); + + it("leaves text unchanged when a send carries no marker", () => { + expect(formatSeenMarkerForProvider("Ship the fix", undefined)).toBe("Ship the fix"); + }); + + it("keeps a slash command at the first character", () => { + const marker = { + lastSeenMessageId: MessageId.make("message-user-1"), + seenAt, + unseenCount: 2, + }; + const command = formatSeenMarkerForProvider(" /review the diff", marker); + expect(command.trim().startsWith("/review the diff")).toBe(true); + expect(command.indexOf(", +): ThreadSeenMarkerSummary | undefined { + if (marker === undefined) return undefined; + const seenIndex = messages.findIndex((message) => message.id === marker.lastSeenMessageId); + if (seenIndex < 0) return undefined; + let unseenCount = 0; + for (let index = seenIndex + 1; index < messages.length; index += 1) { + if (messages[index]!.role === "assistant") unseenCount += 1; + } + if (unseenCount === 0) return undefined; + return { + lastSeenMessageId: marker.lastSeenMessageId, + seenAt: marker.seenAt, + unseenCount, + }; +} + +export function formatSeenMarkerForProvider( + text: string, + marker: ThreadSeenMarkerSummary | undefined, +) { + if (marker === undefined || marker.unseenCount === 0) return text; + const noun = marker.unseenCount === 1 ? "message" : "messages"; + const block = [ + ``, + `The user last saw message ${marker.lastSeenMessageId}; ${marker.unseenCount} ${noun} since are unseen. Open the reply with a short catch-up on only those.`, + "", + ].join("\n"); + if (text.trim().startsWith("/")) return `${text}\n\n${block}`; + return `${block}\n\n${text}`; +}