diff --git a/apps/mobile/src/features/threads/ThreadFeed.tsx b/apps/mobile/src/features/threads/ThreadFeed.tsx index c48e9a16280cb..7df6616b45a9d 100644 --- a/apps/mobile/src/features/threads/ThreadFeed.tsx +++ b/apps/mobile/src/features/threads/ThreadFeed.tsx @@ -245,6 +245,7 @@ import { ThreadWorkLog, WORK_GROUP_TOGGLE_HEIGHT, } from "./thread-work-log"; +import { seenMessagesFromFeed, useThreadSeenMarker } from "./useThreadSeenMarker"; import { appendGuestPendingMessages, appendPendingThreadMessages, @@ -3525,6 +3526,11 @@ export const ThreadFeed = memo(function ThreadFeed(props: ThreadFeedProps) { onHeaderMaterialVisibilityChange?.(visible); }; const feedThreadKey = scopedThreadKey(props.environmentId, props.threadId); + const seenMessages = useMemo(() => seenMessagesFromFeed(props.feed), [props.feed]); + const handleViewableItemsChanged = useThreadSeenMarker({ + threadKey: feedThreadKey, + messages: seenMessages, + }); const [loadedListKey, setLoadedListKey] = useState(null); const [landedListKey, setLandedListKey] = useState(null); // LegendList reports ready, and shows its rows, while rows measured during its initial scroll can @@ -4036,6 +4042,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) => { if (entry.type !== "message") return 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..e9a61dd0d20f9 --- /dev/null +++ b/apps/mobile/src/features/threads/useThreadSeenMarker.test.ts @@ -0,0 +1,168 @@ +import { MessageId, ThreadId } 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, + attachments: [], + runId: null, + streaming: false, + visibility: "local", + sourceThreadId: ThreadId.make("thread"), + 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..25a8228acc8bc --- /dev/null +++ b/apps/mobile/src/features/threads/useThreadSeenMarker.ts @@ -0,0 +1,80 @@ +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"; +import type { ThreadFeedRow } from "./pending-thread-feed"; + +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: ThreadFeedRow }>, +): 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"); + + // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- AppState listener and the dwell timer for this thread + 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]); + + // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- tells the dwell timer when screen focus or the thread's messages change + useEffect(() => { + sessionRef.current?.update({ + active: isFocused && AppState.currentState === "active", + ...(messages.length === 0 ? { visibleIds: [] } : {}), + }); + }, [isFocused, messages]); + + return useCallback((info: OnViewableItemsChangedInfo) => { + visibleIdsRef.current = viewableMessageIds(info.viewableItems); + sessionRef.current?.update({ visibleIds: visibleIdsRef.current }); + }, []); +} diff --git a/apps/mobile/src/state/threadOutboxDelivery.ts b/apps/mobile/src/state/threadOutboxDelivery.ts index b731160f6d7d3..d4501cf2d9503 100644 --- a/apps/mobile/src/state/threadOutboxDelivery.ts +++ b/apps/mobile/src/state/threadOutboxDelivery.ts @@ -26,6 +26,7 @@ import * as Cause from "effect/Cause"; import { AsyncResult, Atom } from "effect/reactivity"; import { createDebugLogger } from "../lib/debugLog"; +import { buildSeenMarker } from "@t3tools/client-runtime/seen-marker"; import { scopedThreadKey } from "../lib/scopedEntities"; import { buildProjectThreadStartTurnInput } from "../lib/projectThreadStartTurn"; import { serializeComposerMessageForServer, uploadedComposerContext } from "../lib/composerContext"; @@ -947,6 +948,9 @@ export function createThreadOutboxDelivery(): { if (!isQueuedMessagePayloadCurrent(persistedMessage, deliveryRevision)) return true; } if (!hasAccess()) return true; + const seenMarker = buildSeenMarker( + scopedThreadKey(queuedMessage.environmentId, queuedMessage.threadId), + ); const deliveryResult = await runDeliveryCommand(threadEnvironment.startTurn, { environmentId: queuedMessage.environmentId, input: { @@ -976,6 +980,7 @@ export function createThreadOutboxDelivery(): { createdAt: queuedMessage.createdAt, dispatchMode: queuedMessage.dispatchMode ?? "start", ...(queuedMessage.freshContext ? { freshContext: true } : {}), + ...(seenMarker ? { seenMarker } : {}), resendAfterSocketLoss: false, }, }); diff --git a/apps/server/src/orchestration-v2/Orchestrator.seen-marker.test.ts b/apps/server/src/orchestration-v2/Orchestrator.seen-marker.test.ts new file mode 100644 index 0000000000000..da9095873b488 --- /dev/null +++ b/apps/server/src/orchestration-v2/Orchestrator.seen-marker.test.ts @@ -0,0 +1,185 @@ +import { assert, it } from "@effect/vitest"; +import { + CommandId, + EventId, + MessageId, + ProjectId, + ProviderDriverKind, + ProviderInstanceId, + ThreadId, + type OrchestrationV2ConversationMessage, + type ThreadSeenMarker, +} from "@t3tools/contracts"; +import { formatSeenMarkerForProvider } from "@t3tools/shared/seenMarker"; +import * as DateTime from "effect/DateTime"; +import * as Effect from "effect/Effect"; +import * as Layer from "effect/Layer"; +import * as SqlitePersistence from "../persistence/Sqlite.ts"; +import { CodexProviderCapabilitiesV2 } from "./Adapters/CodexAdapterV2.ts"; +import * as EventSink from "./EventSink.ts"; +import * as Orchestrator from "./Orchestrator.ts"; +import * as ProviderAdapterRegistry from "./ProviderAdapterRegistry.ts"; +import * as ProviderReplayHarness from "./testkit/ProviderReplayHarness.ts"; +import type * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter"; + +const instanceId = ProviderInstanceId.make("codex"); +const adapter = { + instanceId, + driver: ProviderDriverKind.make("codex"), + getCapabilities: () => Effect.succeed(CodexProviderCapabilitiesV2), + planSelectionTransition: () => Effect.succeed({ type: "apply_on_next_turn" as const }), + openSession: () => Effect.die("No provider process needed for dispatch decisions"), +} as ProviderAdapter.ProviderAdapterV2["Service"]; +const layerDatabase = SqlitePersistence.layerMemory; +const layerTest = Layer.mergeAll( + layerDatabase, + ProviderReplayHarness.layerWithRegistry( + { name: "seen-marker" }, + ProviderAdapterRegistry.layerFromAdapters([adapter]), + { databaseLayer: layerDatabase, runEffectWorker: false }, + ), +); + +const SEEN_AT = "2026-11-20T03:00:00.000Z"; + +const sendWithHistory = ( + threadId: ThreadId, + history: ReadonlyArray, + seenMarker?: ThreadSeenMarker, +) => + Effect.gen(function* () { + const orchestrator = yield* Orchestrator.OrchestratorV2; + const sink = yield* EventSink.EventSinkV2; + yield* orchestrator.dispatch({ + type: "thread.create", + commandId: CommandId.make(`create:${threadId}`), + threadId, + projectId: ProjectId.make("project:seen-marker"), + title: "Thread", + modelSelection: { instanceId, model: "gpt-5" }, + runtimeMode: "full-access", + interactionMode: "default", + branch: null, + worktreePath: null, + createdBy: "user", + creationSource: "web", + }); + const now = yield* DateTime.now; + yield* sink.write({ + events: history.map(([id, role, streaming], index) => ({ + id: EventId.make(`event:${threadId}:${id}`), + type: "message.updated" as const, + threadId, + occurredAt: now, + payload: { + id: MessageId.make(id), + threadId, + runId: null, + nodeId: null, + role, + text: id, + attachments: [], + streaming: streaming === "streaming", + createdBy: role === "user" ? "user" : "agent", + creationSource: role === "user" ? "web" : "provider", + createdAt: DateTime.subtract(now, { seconds: history.length - index }), + updatedAt: now, + } satisfies OrchestrationV2ConversationMessage, + })), + }); + const messageId = MessageId.make(`message-next:${threadId}`); + yield* orchestrator.dispatch({ + type: "message.dispatch", + commandId: CommandId.make(`send:${threadId}`), + threadId, + messageId, + text: "What did I miss?", + attachments: [], + dispatchMode: { type: "start_immediately" }, + createdBy: "user", + creationSource: "web", + ...(seenMarker ? { seenMarker } : {}), + }); + const { messages } = yield* orchestrator.getThreadRecords(threadId, ["messages"]); + return messages.find((message) => message.id === messageId); + }); + +it.layer(layerTest)("seen marker dispatch", (it) => { + it.effect("a send with no marker, including an MCP send, adds no catch-up", () => + Effect.gen(function* () { + const sent = yield* sendWithHistory(ThreadId.make("thread:seen-none"), [ + ["message-user", "user"], + ["message-assistant", "assistant"], + ]); + assert.ok(sent); + assert.isUndefined(sent.seenMarker); + assert.equal( + formatSeenMarkerForProvider("What did I miss?", sent.seenMarker), + "What did I miss?", + ); + }), + ); + + it.effect("counts unseen assistant messages onto the message the founder sends", () => + Effect.gen(function* () { + const sent = yield* sendWithHistory( + ThreadId.make("thread:seen-count"), + [ + ["message-user", "user"], + ["message-assistant-1", "assistant"], + ["message-user-2", "user"], + ["message-assistant-2", "assistant"], + ["message-assistant-live", "assistant", "streaming"], + ], + { lastSeenMessageId: MessageId.make("message-user"), seenAt: SEEN_AT }, + ); + assert.deepEqual(sent?.seenMarker, { + lastSeenMessageId: MessageId.make("message-user"), + seenAt: SEEN_AT, + unseenCount: 2, + }); + assert.include( + formatSeenMarkerForProvider("What did I miss?", sent?.seenMarker), + "The user last saw message message-user; 2 messages since are unseen.", + ); + }), + ); + + it.effect("ignores user messages and messages already seen", () => + Effect.gen(function* () { + const sent = yield* sendWithHistory( + ThreadId.make("thread:seen-later"), + [ + ["message-user", "user"], + ["message-assistant-1", "assistant"], + ["message-user-2", "user"], + ["message-assistant-2", "assistant"], + ], + { lastSeenMessageId: MessageId.make("message-assistant-1"), seenAt: SEEN_AT }, + ); + assert.equal(sent?.seenMarker?.unseenCount, 1); + }), + ); + + it.effect("drops a marker the thread cannot summarize", () => + Effect.gen(function* () { + const missing = yield* sendWithHistory( + ThreadId.make("thread:seen-missing"), + [["message-assistant", "assistant"]], + { lastSeenMessageId: MessageId.make("missing"), seenAt: SEEN_AT }, + ); + const caughtUp = yield* sendWithHistory( + ThreadId.make("thread:seen-caught-up"), + [ + ["message-user", "user"], + ["message-assistant", "assistant"], + ], + { lastSeenMessageId: MessageId.make("message-assistant"), seenAt: SEEN_AT }, + ); + for (const sent of [missing, caughtUp]) { + assert.ok(sent); + assert.isUndefined(sent.seenMarker); + } + }), + ); +}); diff --git a/apps/server/src/orchestration-v2/Orchestrator.ts b/apps/server/src/orchestration-v2/Orchestrator.ts index bab699fa65912..ad3cce997779b 100644 --- a/apps/server/src/orchestration-v2/Orchestrator.ts +++ b/apps/server/src/orchestration-v2/Orchestrator.ts @@ -6084,6 +6084,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio readonly linkedSender?: OrchestrationV2ConversationMessage["linkedSender"]; readonly sentBy?: OrchestrationV2ConversationMessage["sentBy"]; readonly idleCompaction?: OrchestrationV2ConversationMessage["idleCompaction"]; + readonly seenMarker?: OrchestrationV2ConversationMessage["seenMarker"]; readonly delegatedCompletion?: OrchestrationV2ConversationMessage["delegatedCompletion"]; readonly notification?: OrchestrationV2ConversationMessage["notification"]; readonly forceRestart: boolean; @@ -6230,6 +6231,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio ...(input.linkedSender === undefined ? {} : { linkedSender: input.linkedSender }), ...(input.sentBy === undefined ? {} : { sentBy: input.sentBy }), ...(input.idleCompaction === undefined ? {} : { idleCompaction: input.idleCompaction }), + ...(input.seenMarker === undefined ? {} : { seenMarker: input.seenMarker }), id: input.messageId, threadId: input.command.threadId, runId: messageInput.runId, @@ -6893,6 +6895,16 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio ) { projection = yield* getProjectionWithPendingEvents(command.threadId, events); } + const unseenCount = + command.seenMarker === undefined + ? null + : yield* projectionStore + .countAssistantMessagesAfter(command.threadId, command.seenMarker.lastSeenMessageId) + .pipe(mapDispatchError(command)); + const seenMarker = + command.seenMarker !== undefined && unseenCount !== null && unseenCount > 0 + ? { ...command.seenMarker, unseenCount } + : undefined; if (command.manualContinuationOfRunId !== undefined) { const source = projection.runs.find((run) => run.id === command.manualContinuationOfRunId); const limited = latestRootProviderFailure(source ?? null, projection.turnItems); @@ -7498,6 +7510,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio ...(command.linkedSender === undefined ? {} : { linkedSender: command.linkedSender }), ...(command.sentBy === undefined ? {} : { sentBy: command.sentBy }), ...(command.idleCompaction === undefined ? {} : { idleCompaction: command.idleCompaction }), + ...(seenMarker === undefined ? {} : { seenMarker }), forceRestart: dispatchMode.type === "restart_active", }); return; @@ -7794,6 +7807,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio ...(command.linkedSender === undefined ? {} : { linkedSender: command.linkedSender }), ...(command.sentBy === undefined ? {} : { sentBy: command.sentBy }), ...(command.idleCompaction === undefined ? {} : { idleCompaction: command.idleCompaction }), + ...(seenMarker === undefined ? {} : { seenMarker }), ...(command.scheduledTaskId !== undefined && command.modelSelection === undefined ? { followsThreadSelection: true as const } : {}), @@ -8213,6 +8227,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio ...(command.linkedSender === undefined ? {} : { linkedSender: command.linkedSender }), ...(command.sentBy === undefined ? {} : { sentBy: command.sentBy }), ...(command.idleCompaction === undefined ? {} : { idleCompaction: command.idleCompaction }), + ...(seenMarker === undefined ? {} : { seenMarker }), ...(command.scheduledTaskId !== undefined && command.modelSelection === undefined ? { followsThreadSelection: true as const } : {}), @@ -9011,6 +9026,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio ...(command.linkedSender === undefined ? {} : { linkedSender: command.linkedSender }), ...(command.sentBy === undefined ? {} : { sentBy: command.sentBy }), ...(command.idleCompaction === undefined ? {} : { idleCompaction: command.idleCompaction }), + ...(seenMarker === undefined ? {} : { seenMarker }), id: command.messageId, threadId: command.threadId, runId, diff --git a/apps/server/src/orchestration-v2/ProjectionStore.ts b/apps/server/src/orchestration-v2/ProjectionStore.ts index a97180024c12e..0db63f9289069 100644 --- a/apps/server/src/orchestration-v2/ProjectionStore.ts +++ b/apps/server/src/orchestration-v2/ProjectionStore.ts @@ -545,6 +545,10 @@ export interface ProjectionStoreV2Shape { options: ProjectionTimelinePageOptions, ) => Effect.Effect; readonly getMessageCount: (threadId: ThreadId) => Effect.Effect; + readonly countAssistantMessagesAfter: ( + threadId: ThreadId, + messageId: MessageId, + ) => Effect.Effect; /** Bytes of tool output a transcript export is sure to hold, or 0 when it can fit in `limit`. */ readonly getTranscriptByteFloor: ( threadId: ThreadId, @@ -6291,6 +6295,24 @@ export const layer: Layer.Layer = Effect.map((rows) => rows[0]?.count ?? 0), Effect.mapError(controlReadError(threadId)), ); + const countAssistantMessagesAfter: ProjectionStoreV2Shape["countAssistantMessagesAfter"] = ( + threadId, + messageId, + ) => + sql<{ count: number }>` + SELECT COUNT(later.message_id) AS count + FROM orchestration_v2_projection_messages AS seen + LEFT JOIN orchestration_v2_projection_messages AS later + ON later.thread_id = seen.thread_id + AND later.role = 'assistant' + AND later.streaming = 0 + AND (later.created_at, later.message_id) > (seen.created_at, seen.message_id) + WHERE seen.message_id = ${messageId} AND seen.thread_id = ${threadId} + GROUP BY seen.message_id + `.pipe( + Effect.map((rows) => rows[0]?.count ?? null), + Effect.mapError(controlReadError(threadId)), + ); // Tool output reaches the export unchanged, so the bytes of its text, also inside a structured // result, are a floor for the export. Other stored bytes are not: decoding drops fields. A // rolled back run is the only way the export hides a tool row, and rows a fork inherits only @@ -9505,6 +9527,7 @@ export const layer: Layer.Layer = getRunProviderRecords: readOnReader(getRunProviderRecords), isNodeStored: readOnReader(isNodeStored), getMessageCount: readOnReader(getMessageCount), + countAssistantMessagesAfter: readOnReader(countAssistantMessagesAfter), getTranscriptByteFloor: readOnReader(getTranscriptByteFloor), getSubagentCount: readOnReader(getSubagentCount), listAppOwnedChildThreadIds: readOnReader(listAppOwnedChildThreadIds), diff --git a/apps/server/src/orchestration-v2/ProviderTurnControlService.test.ts b/apps/server/src/orchestration-v2/ProviderTurnControlService.test.ts index 532d019ddd6fb..02aa457ca849b 100644 --- a/apps/server/src/orchestration-v2/ProviderTurnControlService.test.ts +++ b/apps/server/src/orchestration-v2/ProviderTurnControlService.test.ts @@ -243,6 +243,7 @@ it.effect( getThreadHistoryPage: () => Effect.die("unused"), getTimelinePage: () => Effect.die("Unused timeline read"), getMessageCount: () => Effect.die("unused message count"), + countAssistantMessagesAfter: () => Effect.die("unused assistant message count"), getTranscriptByteFloor: () => Effect.die("unused transcript byte floor"), hasPendingDelegatedCompletion: () => Effect.die("unused hasPendingDelegatedCompletion"), getSubagentCount: () => Effect.die("unused subagent count"), diff --git a/apps/server/src/orchestration-v2/ProviderTurnControlService.ts b/apps/server/src/orchestration-v2/ProviderTurnControlService.ts index f9727734bf870..69c8e4577bbbf 100644 --- a/apps/server/src/orchestration-v2/ProviderTurnControlService.ts +++ b/apps/server/src/orchestration-v2/ProviderTurnControlService.ts @@ -1,4 +1,5 @@ import { projectComposerContextForProvider } from "@t3tools/shared/composerContextReferences"; +import { formatSeenMarkerForProvider } from "@t3tools/shared/seenMarker"; import { MessageId, type ModelSelection, @@ -455,10 +456,13 @@ export const layer: Layer.Layer< : { modelSelection: input.modelSelection }), message: { messageId: message.id, - text: projectComposerContextForProvider({ - text: message.text, - records: message.context?.records ?? [], - }), + text: formatSeenMarkerForProvider( + projectComposerContextForProvider({ + text: message.text, + records: message.context?.records ?? [], + }), + message.seenMarker, + ), attachments: message.attachments, createdBy: message.createdBy, creationSource: message.creationSource, diff --git a/apps/server/src/orchestration-v2/ProviderTurnStartService.ts b/apps/server/src/orchestration-v2/ProviderTurnStartService.ts index 5996a090bf4bd..ef80b3cc5e6ee 100644 --- a/apps/server/src/orchestration-v2/ProviderTurnStartService.ts +++ b/apps/server/src/orchestration-v2/ProviderTurnStartService.ts @@ -1,5 +1,6 @@ import { modelSelectionsEqual } from "@t3tools/shared/model"; import { projectComposerContextForProvider } from "@t3tools/shared/composerContextReferences"; +import { formatSeenMarkerForProvider } from "@t3tools/shared/seenMarker"; import { CommandId, latestProviderTurnForAttempt, @@ -844,10 +845,13 @@ export const layer: Layer.Layer< }); let effectiveHandoffs = handoffs; let resumeFellBack = false; - const userText = projectComposerContextForProvider({ - text: providerMessage.text, - records: providerMessage.context?.records ?? [], - }); + const userText = formatSeenMarkerForProvider( + projectComposerContextForProvider({ + text: providerMessage.text, + records: providerMessage.context?.records ?? [], + }), + providerMessage.seenMarker, + ); // Native goal commands go verbatim; handoff history waits a turn. const goalDriver = session.driver === "codex" || diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx index 3ccc154bf47be..b3a48acf15393 100644 --- a/apps/web/src/components/ChatView.tsx +++ b/apps/web/src/components/ChatView.tsx @@ -43,6 +43,7 @@ import { useQueuedRunEdit } from "./chat/useQueuedRunEdit"; import { recallCheckoutIsRepo, rememberCheckoutIsRepo } from "./ChatView.logic"; import { useLogicalProjectEnvironments } from "../hooks/useLogicalProjectEnvironments"; import { useStableCallback } from "../hooks/useStableCallback"; +import { useSeenMarkerTracking } from "../hooks/useSeenMarkerTracking"; import { useProjectScriptEditing } from "./chat/useProjectScriptEditing"; import { RightPanelSurfaceContent } from "./chat/RightPanelSurfaceContent"; import { usePendingThreadRequests } from "./chat/usePendingThreadRequests"; @@ -116,6 +117,7 @@ import { scopeProjectRef, scopeThreadRef, } from "@t3tools/client-runtime/environment"; +import { type SeenMessage } from "@t3tools/client-runtime/seen-marker"; import { formatModelSlugName, resolveSelectableModel } from "@t3tools/shared/model"; import { projectScriptCwd, resolveProjectScripts } from "@t3tools/shared/projectScripts"; import { resolveProjectSettings } from "@t3tools/shared/projectSettings"; @@ -400,6 +402,7 @@ import { makeThreadErrorSetter, } from "./ChatView.logic"; +const EMPTY_SEEN_MESSAGES: ReadonlyArray = []; const EMPTY_PROVIDERS: ServerProvider[] = []; const EMPTY_PROVIDER_MODELS: ServerProvider["models"] = []; const EMPTY_USAGE_LIMIT_SOURCES: UsageLimitSourceSnapshots = []; @@ -1618,6 +1621,11 @@ export default function ChatView(props: ChatViewProps) { ); const timelineEmpty = timelineEntries.length === 0 && !hasStreamedTimelineRows; const displayedTimelineKey = activeThreadKey ?? routeThreadKey; + useSeenMarkerTracking({ + threadKey: isServerThread ? activeThreadKey : null, + getScrollNode: () => legendListRef.current?.getScrollableNode() ?? null, + messages: serverProjection?.messages ?? EMPTY_SEEN_MESSAGES, + }); const displayedThreadRef = parseScopedThreadKey(displayedTimelineKey); const { worktreeSetup, diff --git a/apps/web/src/components/chat/useComposerSend.ts b/apps/web/src/components/chat/useComposerSend.ts index 0df3e650593ca..44c155dd95859 100644 --- a/apps/web/src/components/chat/useComposerSend.ts +++ b/apps/web/src/components/chat/useComposerSend.ts @@ -30,6 +30,7 @@ import { RuntimeMode, } from "@t3tools/contracts"; import { deriveThreadTitleSeed } from "@t3tools/client-runtime/operations"; +import { buildSeenMarker } from "@t3tools/client-runtime/seen-marker"; import { wasBootstrapThreadDeleted } from "@t3tools/client-runtime/errors"; import { declinePendingApprovals, @@ -273,6 +274,11 @@ interface ComposerSendInput { readonly linkCheckoutPullRequest: (threadRef: ScopedThreadRef, url: string) => void; } +export function seenMarkerForSend(threadKey: string) { + const seenMarker = buildSeenMarker(threadKey); + return seenMarker ? { seenMarker } : {}; +} + /** * Everything the composer's send button can start: a turn on this thread or a new one, * a multiple-model start, a queued or steering message, a plan follow-up or implementation @@ -1470,6 +1476,7 @@ export function useComposerSend(input: ComposerSendInput) { dispatchMode: turnDispatchMode, ...(freshArm === undefined ? {} : { freshContext: true }), ...(bootstrap ? { bootstrap } : {}), + ...seenMarkerForSend(scopedThreadKey(scopeThreadRef(environmentId, threadIdForSend))), createdAt: messageCreatedAt, }, } diff --git a/apps/web/src/components/chat/useThreadLifecycle.tsx b/apps/web/src/components/chat/useThreadLifecycle.tsx index 4f27c18b75c7d..f94d40e5dbcc3 100644 --- a/apps/web/src/components/chat/useThreadLifecycle.tsx +++ b/apps/web/src/components/chat/useThreadLifecycle.tsx @@ -78,6 +78,7 @@ import { Atom } from "effect/reactivity"; import { environmentThreadDetails } from "../../state/threads"; import { resolveThreadOpenRoute } from "../../lib/sideChatPane"; import type { useLocalDispatchState } from "./useLocalDispatchState"; +import { seenMarkerForSend } from "./useComposerSend"; const RELATED_THREAD_SHELL_WAIT_MS = 1_000; const NO_RUN_STOP_ATOM = Atom.make(null).pipe( Atom.withLabel("web-thread-run-stop:empty"), @@ -555,6 +556,7 @@ export function useThreadLifecycle(input: ThreadLifecycleInput) { modelSelection: context.selectedModelSelection, runtimeMode, interactionMode: DEFAULT_INTERACTION_MODE, + ...seenMarkerForSend(scopedThreadKey(scopeThreadRef(environmentId, threadId))), createdAt, }, }); 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..6601bc2cd5424 --- /dev/null +++ b/apps/web/src/hooks/useSeenMarkerTracking.ts @@ -0,0 +1,135 @@ +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); + + // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- window focus, visibility and scroll listeners plus the dwell timer for this thread + useEffect(() => { + if (threadKey === null) return; + const sampling = startSeenMarkerSampling({ + host: { window, document }, + threadKey, + getScrollNode, + getMessages, + }); + samplingRef.current = sampling; + return () => { + sampling.dispose(); + samplingRef.current = null; + }; + }, [threadKey]); + + // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- resamples the visible DOM rows when the thread's messages change + useEffect(() => { + if (messages.length > 0) samplingRef.current?.requestSample(); + }, [messages]); +} diff --git a/packages/client-runtime/package.json b/packages/client-runtime/package.json index 3fa0378ea3dc8..f2849bbd6df62 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" + }, "./pull-request-diff-fold": { "types": "./src/pullRequestDiffFold.ts", "default": "./src/pullRequestDiffFold.ts" diff --git a/packages/client-runtime/src/operations/commands.ts b/packages/client-runtime/src/operations/commands.ts index 82a05f75011d3..5b7f7dfe39030 100644 --- a/packages/client-runtime/src/operations/commands.ts +++ b/packages/client-runtime/src/operations/commands.ts @@ -198,6 +198,7 @@ export interface StartThreadTurnInput extends ThreadCommandInput { readonly interactionMode: ProviderInteractionMode; readonly bootstrap?: StartThreadBootstrap; readonly sourceProposedPlan?: { readonly threadId: ThreadId; readonly planId: PlanId }; + readonly seenMarker?: import("@t3tools/contracts").ThreadSeenMarker; readonly dispatchMode?: "auto" | "queue" | "steer" | "restart" | "start"; /** Start a new provider session; needs the server's `freshContext` capability. */ readonly freshContext?: boolean; @@ -855,6 +856,7 @@ export const startThreadTurn = Effect.fn("EnvironmentCommands.startThreadTurn")( ? {} : { sourcePlanRef: input.sourceProposedPlan }), ...(input.freshContext ? { freshContext: true } : {}), + ...(input.seenMarker === undefined ? {} : { seenMarker: input.seenMarker }), dispatchMode: { type: "start_immediately" }, }, resendAfterSocketLoss, @@ -885,6 +887,7 @@ export const startThreadTurn = Effect.fn("EnvironmentCommands.startThreadTurn")( ? {} : { sourcePlanRef: input.sourceProposedPlan }), ...(input.freshContext ? { freshContext: true } : {}), + ...(input.seenMarker === undefined ? {} : { seenMarker: input.seenMarker }), ...(requestedMode !== "queue" ? { deliveryIntent: requestedMode } : {}), dispatchMode, }, 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..0f3f4769e1b32 --- /dev/null +++ b/packages/client-runtime/src/seenMarker.ts @@ -0,0 +1,145 @@ +import type { MessageId, ThreadSeenMarker } from "@t3tools/contracts"; + +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; +} + +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(); + +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/orchestrationV2.ts b/packages/contracts/src/orchestrationV2.ts index f51b431c7b98a..c216e6444cb7e 100644 --- a/packages/contracts/src/orchestrationV2.ts +++ b/packages/contracts/src/orchestrationV2.ts @@ -1427,6 +1427,19 @@ export type OrchestrationV2Notification = typeof OrchestrationV2Notification.Typ export const OrchestrationV2IdleCompaction = Schema.Literals(["beforeCacheExpires", "onReturn"]); export type OrchestrationV2IdleCompaction = typeof OrchestrationV2IdleCompaction.Type; +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 OrchestrationV2ConversationMessage = Schema.Struct({ notification: Schema.optional(OrchestrationV2Notification), ...OrchestrationV2CreationFields, @@ -1437,6 +1450,7 @@ export const OrchestrationV2ConversationMessage = Schema.Struct({ linkedSender: Schema.optional(OrchestrationV2LinkedSender), sentBy: Schema.optional(OrchestrationV2MessageSentBy), idleCompaction: Schema.optional(OrchestrationV2IdleCompaction), + seenMarker: Schema.optional(ThreadSeenMarkerSummary), /** * The message is the script a provider-native workflow run executes, not prose. Clients show * the workflow's opening instead and keep the script behind a disclosure. @@ -3450,6 +3464,7 @@ export const OrchestrationV2Command = Schema.Union([ linkedSender: Schema.optional(OrchestrationV2LinkedSender), sentBy: Schema.optional(OrchestrationV2MessageSentBy), idleCompaction: Schema.optional(OrchestrationV2IdleCompaction), + seenMarker: Schema.optional(ThreadSeenMarker), /** Start a new provider session without the thread's earlier context. Never steers. */ freshContext: Schema.optional(Schema.Boolean), commandId: CommandId, diff --git a/packages/shared/package.json b/packages/shared/package.json index 29b36a3583fe1..601e520bd24af 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" + }, "./png": { "types": "./src/png.ts", "import": "./src/png.ts" diff --git a/packages/shared/src/seenMarker.test.ts b/packages/shared/src/seenMarker.test.ts new file mode 100644 index 0000000000000..1190ed7a666ef --- /dev/null +++ b/packages/shared/src/seenMarker.test.ts @@ -0,0 +1,42 @@ +import { MessageId } from "@t3tools/contracts"; +import { describe, expect, it } from "@effect/vitest"; + +import { formatSeenMarkerForProvider } from "./seenMarker.ts"; + +const seenAt = "2026-11-20T03:00:00.000Z"; +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("passes a slash command to the provider unchanged", () => { + const marker = { + lastSeenMessageId: MessageId.make("message-user-1"), + seenAt, + unseenCount: 2, + }; + for (const command of ["/compact", " /review the diff", "/goal pause"]) { + expect(formatSeenMarkerForProvider(command, marker)).toBe(command); + } + const prose = formatSeenMarkerForProvider("Review the diff", marker); + expect(prose.startsWith("`, + `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; + return `${block}\n\n${text}`; +}