Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .agents/skills/verify-t3code/features/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
51 changes: 51 additions & 0 deletions .agents/skills/verify-t3code/features/seen-marker.md
Original file line number Diff line number Diff line change
@@ -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`.
7 changes: 7 additions & 0 deletions apps/mobile/src/features/threads/ThreadFeed.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -2418,6 +2419,11 @@ export const ThreadFeed = memo(function ThreadFeed(props: ThreadFeedProps) {
() => new Map<string, ThreadWorkGroupScrollPosition>(),
[feedThreadKey],
);
const seenMessages = useMemo(() => seenMessagesFromFeed(props.feed), [props.feed]);
const handleViewableItemsChanged = useThreadSeenMarker({
threadKey: feedThreadKey,
messages: seenMessages,
});

useEffect(() => {
reportHeaderMaterialVisibility(false);
Expand Down Expand Up @@ -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
Expand Down
162 changes: 162 additions & 0 deletions apps/mobile/src/features/threads/useThreadSeenMarker.test.ts
Original file line number Diff line number Diff line change
@@ -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: <T extends (...args: never[]) => unknown>(callback: T) => callback,
useCallback: <T extends (...args: never[]) => 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<typeof useThreadSeenMarker>) {
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<typeof onViewable>[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]);
});
});

74 changes: 74 additions & 0 deletions apps/mobile/src/features/threads/useThreadSeenMarker.ts
Original file line number Diff line number Diff line change
@@ -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<ThreadFeedEntry>): 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<SeenMessage>;
}) {
const { threadKey, messages } = input;
const isFocused = useIsFocused();
const sessionRef = useRef<SeenMarkerSession | null>(null);
const visibleIdsRef = useRef<ReadonlyArray<MessageId>>([]);
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<typeof setTimeout>),
},
});
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<ThreadFeedEntry>) => {
visibleIdsRef.current = viewableMessageIds(info.viewableItems);
sessionRef.current?.update({ visibleIds: visibleIdsRef.current });
}, []);
}
5 changes: 5 additions & 0 deletions apps/mobile/src/state/use-thread-outbox-drain.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand Down Expand Up @@ -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: {
Expand All @@ -822,6 +826,7 @@ export function useThreadOutboxDrain(): void {
modelSelection: sendSettings.modelSelection,
runtimeMode: sendSettings.runtimeMode,
interactionMode: sendSettings.interactionMode,
...(seenMarker ? { seenMarker } : {}),
createdAt: queuedMessage.createdAt,
},
});
Expand Down
12 changes: 8 additions & 4 deletions apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand Down Expand Up @@ -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 }
Expand Down
Loading