Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

feat(in-app-agent): Surface background conversation activity and toast cards (#15852)

Lysander Kiesel33bc57f19a48
diff --git a/packages/shared/src/in-app-agent/backgroundWatch.ts b/packages/shared/src/in-app-agent/backgroundWatch.ts
index c18e4023b2..2878726658 100644
--- a/packages/shared/src/in-app-agent/backgroundWatch.ts
+++ b/packages/shared/src/in-app-agent/backgroundWatch.ts
@@ -95,3 +95,23 @@ export function isActiveInAppAgentRunStatus(
): boolean {
return IN_APP_AGENT_ACTIVE_RUN_STATUSES.includes(status);
}
+
+/**
+ * Runs the user still has to deal with: executing, or parked on their decision.
+ *
+ * Wider than {@link IN_APP_AGENT_ACTIVE_RUN_STATUSES} on purpose. A parked
+ * approval sets `finishedAt`, so `finishedAt: null` finds executing runs but
+ * silently misses the one state that is literally waiting for the user.
+ */
+export const IN_APP_AGENT_UNSETTLED_RUN_STATUSES: readonly InAppAgentRunStatus[] =
+ [
+ InAppAgentRunStatus.QUEUED,
+ InAppAgentRunStatus.RUNNING,
+ InAppAgentRunStatus.AWAITING_APPROVAL,
+ ];
+
+export function isUnsettledInAppAgentRunStatus(
+ status: InAppAgentRunStatus,
+): boolean {
+ return IN_APP_AGENT_UNSETTLED_RUN_STATUSES.includes(status);
+}
diff --git a/packages/shared/src/in-app-agent/server/runLifecycle.ts b/packages/shared/src/in-app-agent/server/runLifecycle.ts
index 0a8ed04f2e..702f2abf1e 100644
--- a/packages/shared/src/in-app-agent/server/runLifecycle.ts
+++ b/packages/shared/src/in-app-agent/server/runLifecycle.ts
@@ -7,7 +7,10 @@ import {
import { Prisma } from "../../db";
import type { InAppAgentRun, PrismaClient } from "../../db";
import { logger } from "../../server";
-import { buildInAppAgentApprovalDecisionEvent } from "../backgroundWatch";
+import {
+ buildInAppAgentApprovalDecisionEvent,
+ IN_APP_AGENT_UNSETTLED_RUN_STATUSES,
+} from "../backgroundWatch";
import type { AgUiEvent } from "../schema";
import type { InAppAgentPrefixedLangfuseMcpToolName } from "./tools";
import {
@@ -355,13 +358,7 @@ export async function cancelConversationRunsInTransaction(params: {
projectId: params.projectId,
conversationId: params.conversationId,
// Parked approvals have finishedAt set but remain unsettled.
- status: {
- in: [
- InAppAgentRunStatus.QUEUED,
- InAppAgentRunStatus.RUNNING,
- InAppAgentRunStatus.AWAITING_APPROVAL,
- ],
- },
+ status: { in: [...IN_APP_AGENT_UNSETTLED_RUN_STATUSES] },
},
select: { id: true, status: true },
});
@@ -541,11 +538,7 @@ async function reconcileConversationRunsInTransaction(params: {
projectId,
conversationId,
status: {
- in: [
- InAppAgentRunStatus.QUEUED,
- InAppAgentRunStatus.RUNNING,
- InAppAgentRunStatus.AWAITING_APPROVAL,
- ],
+ in: [...IN_APP_AGENT_UNSETTLED_RUN_STATUSES],
},
},
select: {
@@ -592,7 +585,16 @@ async function reconcileConversationRunsInTransaction(params: {
return reconciled;
}
-function classifyStaleRun(
+/**
+ * Decide whether a non-terminal run has already missed every deadline that
+ * should have failed it. Pure: callers choose whether to act on the verdict.
+ *
+ * Reconciliation writes the verdict; read paths that only need to render a run
+ * may apply it without writing, so a dead worker does not leave a conversation
+ * spinning until someone opens it (`reconcileConversationRuns` is the only
+ * authority that persists the transition).
+ */
+export function classifyStaleRun(
run: {
status: string | null;
createdAt: Date;
diff --git a/web/src/__tests__/server/in-app-agent-background-run.servertest.ts b/web/src/__tests__/server/in-app-agent-background-run.servertest.ts
index d4f1b808b3..873f503b59 100644
--- a/web/src/__tests__/server/in-app-agent-background-run.servertest.ts
+++ b/web/src/__tests__/server/in-app-agent-background-run.servertest.ts
@@ -1289,4 +1289,54 @@ describe("in-app agent background runs", () => {
expect(enqueuedJobs).toHaveLength(0);
});
+
+ it("lists the newest run per conversation and classifies a dead worker without writing", async () => {
+ const { caller, projectId, userId } = await createCaller();
+ const conversation = await createConversation({ projectId, userId });
+
+ await prisma.inAppAgentRun.create({
+ data: {
+ id: createInAppAgentRunId(),
+ projectId,
+ conversationId: conversation.id,
+ triggeredByUserId: userId,
+ status: InAppAgentRunStatus.SUCCEEDED,
+ finishedAt: new Date(Date.now() - 10 * 60_000),
+ createdAt: new Date(Date.now() - 10 * 60_000),
+ request: { kind: "userMessage", context: [] },
+ },
+ });
+ const deadRun = await prisma.inAppAgentRun.create({
+ data: {
+ id: createInAppAgentRunId(),
+ projectId,
+ conversationId: conversation.id,
+ triggeredByUserId: userId,
+ status: InAppAgentRunStatus.RUNNING,
+ claimedAt: new Date(Date.now() - 5 * 60_000),
+ heartbeatAt: new Date(Date.now() - 5 * 60_000),
+ createdAt: new Date(Date.now() - 5 * 60_000),
+ request: { kind: "userMessage", context: [] },
+ },
+ });
+
+ const listed = await caller.listConversations({ projectId, limit: 50 });
+
+ // The newest run wins, and a run whose worker stopped reporting is served
+ // as failed even though nothing has written that verdict yet.
+ expect(
+ listed.conversations.find((row) => row.id === conversation.id)?.latestRun,
+ ).toEqual({
+ id: deadRun.id,
+ status: InAppAgentRunStatus.FAILED,
+ errorCode: InAppAgentRunErrorCode.WORKER_LOST,
+ cancelRequested: false,
+ });
+
+ const stored = await prisma.inAppAgentRun.findFirstOrThrow({
+ where: { id: deadRun.id, projectId },
+ });
+ expect(stored.status).toBe(InAppAgentRunStatus.RUNNING);
+ expect(stored.finishedAt).toBeNull();
+ });
});
diff --git a/web/src/components/nav/in-app-ai-agent-button.clienttest.tsx b/web/src/components/nav/in-app-ai-agent-button.clienttest.tsx
index 24c68907be..10c23105e1 100644
--- a/web/src/components/nav/in-app-ai-agent-button.clienttest.tsx
+++ b/web/src/components/nav/in-app-ai-agent-button.clienttest.tsx
@@ -4,6 +4,7 @@ import { InAppAiAgentButton } from "./in-app-ai-agent-button";
const mocks = vi.hoisted(() => ({
open: false,
+ attentionCount: 0,
setOpen: vi.fn(),
openAssistant: vi.fn().mockReturnValue(true),
}));
@@ -12,6 +13,7 @@ vi.mock("@/src/features/in-app-agent/components/InAppAiAgentProvider", () => ({
useCanUseInAppAgent: () => true,
useInAppAiAgent: () => ({
open: mocks.open,
+ attentionCount: mocks.attentionCount,
setOpen: mocks.setOpen,
openAssistant: mocks.openAssistant,
}),
@@ -20,6 +22,7 @@ vi.mock("@/src/features/in-app-agent/components/InAppAiAgentProvider", () => ({
describe("InAppAiAgentButton", () => {
beforeEach(() => {
mocks.open = false;
+ mocks.attentionCount = 0;
mocks.setOpen.mockReset();
mocks.openAssistant.mockReset().mockReturnValue(true);
});
diff --git a/web/src/components/nav/in-app-ai-agent-button.tsx b/web/src/components/nav/in-app-ai-agent-button.tsx
index 47feb0a4b4..bdf7ca677a 100644
--- a/web/src/components/nav/in-app-ai-agent-button.tsx
+++ b/web/src/components/nav/in-app-ai-agent-button.tsx
@@ -23,7 +23,7 @@ export const InAppAiAgentButton = ({
}: {
prominent?: boolean;
} = {}) => {
- const { open, setOpen, openAssistant } = useInAppAiAgent();
+ const { open, setOpen, openAssistant, attentionCount } = useInAppAiAgent();
const canUseAssistant = useCanUseInAppAgent();
const toggleAssistant = useCallback(
@@ -66,11 +66,18 @@ export const InAppAiAgentButton = ({
return null;
}
+ const attentionSuffix =
+ attentionCount > 0
+ ? ` (${attentionCount} ${attentionCount === 1 ? "needs" : "need"} attention)`
+ : "";
+
return (
<Button
type="button"
variant="outline"
- aria-label={open ? "Close assistant" : "Open assistant"}
+ // Count lives on the button name — a nested badge aria-label is ignored
+ // once the parent already has aria-label.
+ aria-label={`${open ? "Close" : "Open"} assistant${attentionSuffix}`}
aria-pressed={open}
data-ignore-outside-interaction
onClick={() => toggleAssistant("top_nav")}
@@ -88,7 +95,7 @@ export const InAppAiAgentButton = ({
: undefined
}
className={cn(
- "gap-2",
+ "relative gap-2",
// Compact icon-only launcher for the top bar.
prominent && "size-9 shrink-0 px-0",
!prominent &&
@@ -99,6 +106,17 @@ export const InAppAiAgentButton = ({
<BotMessageSquare
className={cn("h-4 w-4", prominent && open && "text-primary-accent")}
/>
+ {/* Conversations still owed a look. Anchored to the button rather than
+ the icon so it survives the prominent (icon-only) variant. Visual
+ only — accessible name is on the button. */}
+ {attentionCount > 0 && (
+ <span
+ aria-hidden="true"
+ className="bg-primary-accent text-primary-foreground absolute -top-1 -right-1 flex h-4 min-w-4 items-center justify-center rounded-full px-1 text-[10px] leading-none font-bold"
+ >
+ {attentionCount > 99 ? "99+" : attentionCount}
+ </span>
+ )}
{/* The prominent launcher is a fixed 36px square (top bar, below md), so
it stays strictly icon-only — the `sm:inline` label would otherwise
reveal in the 640–767px band and overflow the box. */}
diff --git a/web/src/features/in-app-agent/components/ControlledInAppAgentWindow.tsx b/web/src/features/in-app-agent/components/ControlledInAppAgentWindow.tsx
index 2e1ab47e11..744d188b09 100644
--- a/web/src/features/in-app-agent/components/ControlledInAppAgentWindow.tsx
+++ b/web/src/features/in-app-agent/components/ControlledInAppAgentWindow.tsx
@@ -67,6 +67,7 @@ export function ControlledInAppAgentWindow(
) {
const router = useRouter();
const {
+ activityByConversationId,
conversations,
error,
hasMoreConversations,
@@ -187,6 +188,7 @@ export function ControlledInAppAgentWindow(
quickActionResetKey={quickActionResetKey}
screenContextDescription={screenContextDescription}
conversations={conversations}
+ activityByConversationId={activityByConversationId}
hasMoreConversations={hasMoreConversations}
isLoadingMoreConversations={isLoadingMoreConversations}
selectedConversationId={selectedConversationId}
diff --git a/web/src/features/in-app-agent/components/ConversationActivityIndicator.tsx b/web/src/features/in-app-agent/components/ConversationActivityIndicator.tsx
new file mode 100644
index 0000000000..ff9a328fe7
--- /dev/null
+++ b/web/src/features/in-app-agent/components/ConversationActivityIndicator.tsx
@@ -0,0 +1,66 @@
+import { CircleAlert, Loader2 } from "lucide-react";
+import { type ReactNode } from "react";
+
+import { cn } from "@/src/utils/tailwind";
+import type { InAppAgentActivityState } from "@/src/features/in-app-agent/lib/inAppAgentActivity";
+
+/**
+ * Trailing state for one recent-conversation row. Exactly one can show, so the
+ * caller's priority order is the design: needs you, then doing, then did.
+ */
+export function ConversationActivityIndicator({
+ state,
+}: {
+ state: InAppAgentActivityState;
+}) {
+ if (state === "approval") {
+ return (
+ <ConversationActivityIndicatorSlot label="Needs your approval">
+ <CircleAlert className="text-primary-accent size-3" />
+ </ConversationActivityIndicatorSlot>
+ );
+ }
+
+ if (state === "running") {
+ return (
+ <ConversationActivityIndicatorSlot label="Working">
+ <Loader2 className="text-muted-foreground size-3 animate-spin" />
+ </ConversationActivityIndicatorSlot>
+ );
+ }
+
+ return (
+ <ConversationActivityIndicatorSlot
+ label={state === "failed-unread" ? "Failed" : "Finished"}
+ >
+ <span
+ className={cn(
+ "size-1.5 rounded-full",
+ state === "failed-unread" ? "bg-destructive" : "bg-primary-accent",
+ )}
+ />
+ </ConversationActivityIndicatorSlot>
+ );
+}
+
+/**
+ * Fixed-size box: the dot is half the width of the icons, so without it the
+ * column zig-zags. Named here because a bare span cannot carry a label.
+ */
+function ConversationActivityIndicatorSlot({
+ label,
+ children,
+}: {
+ label: string;
+ children: ReactNode;
+}) {
+ return (
+ <span
+ role="img"
+ aria-label={label}
+ className="flex size-3 shrink-0 items-center justify-center"
+ >
+ {children}
+ </span>
+ );
+}
diff --git a/web/src/features/in-app-agent/components/InAppAgentActivityCards.stories.tsx b/web/src/features/in-app-agent/components/InAppAgentActivityCards.stories.tsx
new file mode 100644
index 0000000000..ffc356fe4a
--- /dev/null
+++ b/web/src/features/in-app-agent/components/InAppAgentActivityCards.stories.tsx
@@ -0,0 +1,115 @@
+import preview from "../../../../.storybook/preview";
+import { expect, fn, userEvent, within } from "storybook/test";
+import {
+ InAppAgentActivityCards,
+ type InAppAgentActivityCard,
+} from "./InAppAgentActivityCards";
+
+const card = (
+ overrides: Partial<InAppAgentActivityCard> &
+ Pick<InAppAgentActivityCard, "activityKey" | "state">,
+): InAppAgentActivityCard => ({
+ conversationId: "conversation-1",
+ runId: overrides.activityKey.split(":")[0] ?? "run-1",
+ title: "Latency outliers",
+ ...overrides,
+});
+
+const meta = preview.meta({
+ component: InAppAgentActivityCards,
+ args: {
+ onOpen: fn(),
+ onDismiss: fn(),
+ cards: [],
+ },
+});
+
+export const Empty = meta.story({});
+
+export const ApprovalRequired = meta.story({
+ args: {
+ cards: [
+ card({
+ activityKey: "run-1:AWAITING_APPROVAL",
+ state: "approval",
+ title: "Create the eval dataset",
+ }),
+ ],
+ },
+});
+
+export const Finished = meta.story({
+ args: {
+ cards: [card({ activityKey: "run-1:SUCCEEDED", state: "done-unread" })],
+ },
+});
+
+export const Failed = meta.story({
+ args: {
+ cards: [
+ card({
+ activityKey: "run-1:FAILED",
+ state: "failed-unread",
+ title: "Score correlation",
+ }),
+ ],
+ },
+});
+
+export const UntitledConversation = meta.story({
+ args: {
+ cards: [
+ card({
+ activityKey: "run-1:SUCCEEDED",
+ state: "done-unread",
+ title: null,
+ }),
+ ],
+ },
+});
+
+/** Approvals sort to the top regardless of the order they arrived in. */
+export const Stacked = meta.story({
+ args: {
+ cards: [
+ card({
+ conversationId: "conversation-1",
+ activityKey: "run-1:SUCCEEDED",
+ state: "done-unread",
+ title: "Finished while away",
+ }),
+ card({
+ conversationId: "conversation-2",
+ activityKey: "run-2:AWAITING_APPROVAL",
+ state: "approval",
+ title: "Needs your approval",
+ }),
+ card({
+ conversationId: "conversation-3",
+ activityKey: "run-3:FAILED",
+ state: "failed-unread",
+ title: "Failed while away",
+ }),
+ ],
+ },
+});
+
+export const OpensAndDismisses = meta.story({
+ name: "(Test) Opens And Dismisses",
+ args: {
+ cards: [card({ activityKey: "run-1:SUCCEEDED", state: "done-unread" })],
+ },
+ play: async ({ args, canvasElement }) => {
+ const canvas = within(canvasElement);
+
+ await userEvent.click(canvas.getByText("Latency outliers"));
+ await expect(args.onOpen).toHaveBeenCalledWith(
+ expect.objectContaining({ conversationId: "conversation-1" }),
+ );
+
+ await userEvent.click(canvas.getByRole("button", { name: "Dismiss" }));
+ await expect(args.onDismiss).toHaveBeenCalledWith(
+ expect.objectContaining({ activityKey: "run-1:SUCCEEDED" }),
+ );
+ },
+});
diff --git a/web/src/features/in-app-agent/components/InAppAgentActivityCards.tsx b/web/src/features/in-app-agent/components/InAppAgentActivityCards.tsx
new file mode 100644
index 0000000000..8fc845d24c
--- /dev/null
+++ b/web/src/features/in-app-agent/components/InAppAgentActivityCards.tsx
@@ -0,0 +1,122 @@
+import { BotMessageSquare, X } from "lucide-react";
+
+import { Button } from "@/src/components/ui/button";
+import { cn } from "@/src/utils/tailwind";
+import type { InAppAgentActivityState } from "@/src/features/in-app-agent/lib/inAppAgentActivity";
+
+/** Approvals first: a question outranks a result the user can read later. */
+const CARD_PRIORITY: Record<string, number> = {
+ approval: 0,
+ "failed-unread": 1,
+ "done-unread": 2,
+};
+
+const MAX_VISIBLE_CARDS = 3;
+
+export type InAppAgentActivityCard = {
+ conversationId: string;
+ activityKey: string;
+ runId: string;
+ title: string | null;
+ state: Exclude<InAppAgentActivityState, "running">;
+};
+
+export function selectInAppAgentActivityCards(
+ cards: readonly InAppAgentActivityCard[],
+): InAppAgentActivityCard[] {
+ return [...cards]
+ .sort(
+ (a, b) => (CARD_PRIORITY[a.state] ?? 9) - (CARD_PRIORITY[b.state] ?? 9),
+ )
+ .slice(0, MAX_VISIBLE_CARDS);
+}
+
+function getCardCopy(state: InAppAgentActivityCard["state"]) {
+ // Lead with "Assistant" so the toast reads as the same product as the
+ // launcher (BotMessageSquare), not a generic system alert.
+ if (state === "approval") {
+ return {
+ label: "Assistant needs your approval",
+ tone: "accent" as const,
+ };
+ }
+
+ if (state === "failed-unread") {
+ return { label: "Assistant run failed", tone: "destructive" as const };
+ }
+
+ return { label: "Assistant finished", tone: "accent" as const };
+}
+
+/** Pure floating stack: ordering/cap live here; callers own delivery lifecycle. */
+export function InAppAgentActivityCards({
+ cards,
+ onOpen,
+ onDismiss,
+}: {
+ cards: readonly InAppAgentActivityCard[];
+ onOpen: (card: InAppAgentActivityCard) => void;
+ onDismiss: (card: InAppAgentActivityCard) => void;
+}) {
+ const visible = selectInAppAgentActivityCards(cards);
+
+ if (visible.length === 0) {
+ return null;
+ }
+
+ return (
+ <div className="top-banner-offset pointer-events-none fixed right-4 flex w-80 flex-col gap-2 pt-4">
+ {visible.map((card) => {
+ const { label, tone } = getCardCopy(card.state);
+ const conversationTitle = card.title?.trim() || "Untitled conversation";
+
+ return (
+ <div
+ key={card.activityKey}
+ role="status"
+ className="bg-background pointer-events-auto flex items-start gap-2 rounded-md border p-3 shadow-lg"
+ >
+ <BotMessageSquare
+ className={cn(
+ "mt-0.5 size-4 shrink-0",
+ tone === "destructive"
+ ? "text-destructive"
+ : "text-primary-accent",
+ )}
+ aria-hidden
+ />
+ <button
+ type="button"
+ className="min-w-0 flex-1 text-left"
+ onClick={() => {
+ onOpen(card);
+ }}
+ >
+ <p className="truncate text-sm font-bold" title={label}>
+ {label}
+ </p>
+ <p
+ className="text-muted-foreground truncate text-xs"
+ title={conversationTitle}
+ >
+ {conversationTitle}
+ </p>
+ </button>
+ <Button
+ type="button"
+ variant="ghost"
+ size="icon-xs"
+ className="text-muted-foreground -mt-1 -mr-1 shrink-0"
+ aria-label="Dismiss"
+ onClick={() => {
+ onDismiss(card);
+ }}
+ >
+ <X className="size-3" />
+ </Button>
+ </div>
+ );
+ })}
+ </div>
+ );
+}
diff --git a/web/src/features/in-app-agent/components/InAppAgentActivityNotifications.clienttest.tsx b/web/src/features/in-app-agent/components/InAppAgentActivityNotifications.clienttest.tsx
new file mode 100644
index 0000000000..cb35c5cf6a
--- /dev/null
+++ b/web/src/features/in-app-agent/components/InAppAgentActivityNotifications.clienttest.tsx
@@ -0,0 +1,194 @@
+import { act, fireEvent, render, screen, within } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { InAppAgentActivityNotifications } from "./InAppAgentActivityNotifications";
+import type { InAppAgentActivityCard } from "./InAppAgentActivityCards";
+
+vi.mock("@/src/components/ui/layer", () => ({
+ Layer: ({ children }: { children?: unknown }) => children,
+}));
+
+const card = (
+ overrides: Partial<InAppAgentActivityCard> &
+ Pick<InAppAgentActivityCard, "conversationId" | "activityKey" | "state">,
+): InAppAgentActivityCard => ({
+ runId: overrides.activityKey.split(":")[0] ?? "run",
+ title: overrides.title ?? overrides.conversationId,
+ ...overrides,
+});
+
+describe("InAppAgentActivityNotifications", () => {
+ beforeEach(() => {
+ vi.useFakeTimers();
+ });
+
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ it("expires results and approvals on the same timer and does not deliver capped cards", () => {
+ const onDelivered = vi.fn();
+ const onOpenConversation = vi.fn();
+
+ const { rerender } = render(
+ <InAppAgentActivityNotifications
+ notifications={[
+ card({
+ conversationId: "c1",
+ activityKey: "run-1:AWAITING_APPROVAL",
+ state: "approval",
+ title: "Needs you",
+ }),
+ ]}
+ onDelivered={onDelivered}
+ onOpenConversation={onOpenConversation}
+ />,
+ );
+
+ expect(screen.getByText("Needs you")).toBeInTheDocument();
+
+ rerender(
+ <InAppAgentActivityNotifications
+ notifications={[
+ card({
+ conversationId: "c1",
+ activityKey: "run-1:AWAITING_APPROVAL",
+ state: "approval",
+ title: "Needs you",
+ }),
+ card({
+ conversationId: "c2",
+ activityKey: "run-2:SUCCEEDED",
+ state: "done-unread",
+ title: "Second",
+ }),
+ card({
+ conversationId: "c3",
+ activityKey: "run-3:SUCCEEDED",
+ state: "done-unread",
+ title: "Third",
+ }),
+ card({
+ conversationId: "c4",
+ activityKey: "run-4:SUCCEEDED",
+ state: "done-unread",
+ title: "Fourth",
+ }),
+ ]}
+ onDelivered={onDelivered}
+ onOpenConversation={onOpenConversation}
+ />,
+ );
+
+ expect(screen.getByText("Needs you")).toBeInTheDocument();
+ expect(screen.queryByText("Fourth")).not.toBeInTheDocument();
+
+ act(() => {
+ vi.advanceTimersByTime(8_000);
+ });
+
+ expect(onDelivered).toHaveBeenCalledWith([
+ {
+ conversationId: "c1",
+ activityKey: "run-1:AWAITING_APPROVAL",
+ },
+ ]);
+ expect(screen.queryByText("Needs you")).not.toBeInTheDocument();
+ expect(screen.getByText("Fourth")).toBeInTheDocument();
+
+ act(() => {
+ vi.advanceTimersByTime(8_000);
+ });
+
+ const deliveredKeys = onDelivered.mock.calls.flatMap((call) =>
+ call[0].map((entry: { activityKey: string }) => entry.activityKey),
+ );
+ expect(deliveredKeys).toEqual(
+ expect.arrayContaining([
+ "run-1:AWAITING_APPROVAL",
+ "run-2:SUCCEEDED",
+ "run-3:SUCCEEDED",
+ "run-4:SUCCEEDED",
+ ]),
+ );
+ expect(deliveredKeys).toHaveLength(4);
+ });
+
+ it("delivers a previously shown card when a higher-priority arrival evicts it", () => {
+ const onDelivered = vi.fn();
+ const onOpenConversation = vi.fn();
+
+ const doneCards = [
+ card({
+ conversationId: "c1",
+ activityKey: "run-1:SUCCEEDED",
+ state: "done-unread",
+ title: "First",
+ }),
+ card({
+ conversationId: "c2",
+ activityKey: "run-2:SUCCEEDED",
+ state: "done-unread",
+ title: "Second",
+ }),
+ card({
+ conversationId: "c3",
+ activityKey: "run-3:SUCCEEDED",
+ state: "done-unread",
+ title: "Third",
+ }),
+ ];
+
+ const { rerender } = render(
+ <InAppAgentActivityNotifications
+ notifications={doneCards}
+ onDelivered={onDelivered}
+ onOpenConversation={onOpenConversation}
+ />,
+ );
+
+ expect(screen.getByText("Third")).toBeInTheDocument();
+
+ const withApproval = [
+ ...doneCards,
+ card({
+ conversationId: "c4",
+ activityKey: "run-4:AWAITING_APPROVAL",
+ state: "approval",
+ title: "Needs you",
+ }),
+ ];
+
+ rerender(
+ <InAppAgentActivityNotifications
+ notifications={withApproval}
+ onDelivered={onDelivered}
+ onOpenConversation={onOpenConversation}
+ />,
+ );
+
+ expect(screen.getByText("Needs you")).toBeInTheDocument();
+ expect(screen.queryByText("Third")).not.toBeInTheDocument();
+ expect(onDelivered).toHaveBeenCalledWith([
+ {
+ conversationId: "c3",
+ activityKey: "run-3:SUCCEEDED",
+ },
+ ]);
+
+ const approvalCard = screen
+ .getByText("Needs you")
+ .closest('[role="status"]');
+ expect(approvalCard).toBeInstanceOf(HTMLElement);
+ fireEvent.click(
+ within(approvalCard as HTMLElement).getByRole("button", {
+ name: "Dismiss",
+ }),
+ );
+
+ expect(screen.queryByText("Needs you")).not.toBeInTheDocument();
+ expect(screen.queryByText("Third")).not.toBeInTheDocument();
+ expect(screen.getByText("First")).toBeInTheDocument();
+ expect(screen.getByText("Second")).toBeInTheDocument();
+ });
+});
diff --git a/web/src/features/in-app-agent/components/InAppAgentActivityNotifications.tsx b/web/src/features/in-app-agent/components/InAppAgentActivityNotifications.tsx
new file mode 100644
index 0000000000..ef3bdd2e6e
--- /dev/null
+++ b/web/src/features/in-app-agent/components/InAppAgentActivityNotifications.tsx
@@ -0,0 +1,181 @@
+"use client";
+
+import { useEffect, useMemo, useRef, useState } from "react";
+
+import { Layer } from "@/src/components/ui/layer";
+import {
+ InAppAgentActivityCards,
+ selectInAppAgentActivityCards,
+ type InAppAgentActivityCard,
+} from "@/src/features/in-app-agent/components/InAppAgentActivityCards";
+
+/** Same TTL for results and approvals: toast is heads-up, not a sticky prompt. */
+const CARD_TTL_MS = 8_000;
+
+export type InAppAgentActivityNotification = InAppAgentActivityCard;
+
+/**
+ * Lifecycle for the floating stack. Cap before timers so hidden cards stay undelivered.
+ * Assistant-owned (not Sonner) so long-lived approvals do not mute other toasts.
+ */
+export function InAppAgentActivityNotifications({
+ notifications,
+ onOpenConversation,
+ onDelivered,
+}: {
+ notifications: readonly InAppAgentActivityNotification[];
+ onOpenConversation: (conversationId: string) => void;
+ onDelivered: (
+ entries: ReadonlyArray<{ conversationId: string; activityKey: string }>,
+ ) => void;
+}) {
+ const [dismissedKeys, setDismissedKeys] = useState<ReadonlySet<string>>(
+ () => new Set(),
+ );
+ const resultTimersRef = useRef(new Map<string, number>());
+ /** Activity keys that have entered the visible stack (got a timer). */
+ const shownActivityKeysRef = useRef(new Set<string>());
+ const pendingEvictionDeliveriesRef = useRef<
+ Array<{ conversationId: string; activityKey: string }>
+ >([]);
+ const onDeliveredRef = useRef(onDelivered);
+ onDeliveredRef.current = onDelivered;
+
+ const selected = useMemo(
+ () =>
+ selectInAppAgentActivityCards(
+ notifications.filter(
+ (notification) => !dismissedKeys.has(notification.activityKey),
+ ),
+ ),
+ [dismissedKeys, notifications],
+ );
+
+ // Deliver previously-shown cards that leave the top-3 window (eviction).
+ // setState-during-render so we do not sync dismissedKeys from props in an
+ // effect (https://react.dev/learn/you-might-not-need-an-effect). Parent
+ // delivery is flushed after commit via the timer effect below.
+ {
+ const selectedKeys = new Set(selected.map((card) => card.activityKey));
+ const evicted = notifications.filter(
+ (card) =>
+ shownActivityKeysRef.current.has(card.activityKey) &&
+ !selectedKeys.has(card.activityKey) &&
+ !dismissedKeys.has(card.activityKey),
+ );
+
+ if (evicted.length > 0) {
+ setDismissedKeys(
+ (current) =>
+ new Set([...current, ...evicted.map((card) => card.activityKey)]),
+ );
+ pendingEvictionDeliveriesRef.current.push(
+ ...evicted.map((card) => ({
+ conversationId: card.conversationId,
+ activityKey: card.activityKey,
+ })),
+ );
+ for (const card of evicted) {
+ shownActivityKeysRef.current.delete(card.activityKey);
+ }
+ }
+ }
+
+ const retire = (cards: readonly InAppAgentActivityCard[]) => {
+ if (cards.length === 0) {
+ return;
+ }
+
+ for (const card of cards) {
+ const timer = resultTimersRef.current.get(card.activityKey);
+ if (timer !== undefined) {
+ window.clearTimeout(timer);
+ resultTimersRef.current.delete(card.activityKey);
+ }
+ shownActivityKeysRef.current.delete(card.activityKey);
+ }
+
+ setDismissedKeys(
+ (current) =>
+ new Set([...current, ...cards.map((card) => card.activityKey)]),
+ );
+ onDelivered(
+ cards.map((card) => ({
+ conversationId: card.conversationId,
+ activityKey: card.activityKey,
+ })),
+ );
+ };
+
+ // Timers are an external system. Keep this separate from unmount cleanup:
+ // a dependency-change cleanup that cleared every timer would reset TTLs
+ // whenever the visible stack changes.
+ useEffect(() => {
+ const pending = pendingEvictionDeliveriesRef.current;
+ if (pending.length > 0) {
+ pendingEvictionDeliveriesRef.current = [];
+ onDeliveredRef.current(pending);
+ }
+
+ const selectedByKey = new Map(
+ selected.map((card) => [card.activityKey, card]),
+ );
+
+ for (const card of selected) {
+ shownActivityKeysRef.current.add(card.activityKey);
+
+ // Keep existing timers so a new sibling card does not reset older ones.
+ if (resultTimersRef.current.has(card.activityKey)) {
+ continue;
+ }
+
+ const timeout = window.setTimeout(() => {
+ resultTimersRef.current.delete(card.activityKey);
+ shownActivityKeysRef.current.delete(card.activityKey);
+ setDismissedKeys((current) => new Set([...current, card.activityKey]));
+ onDeliveredRef.current([
+ {
+ conversationId: card.conversationId,
+ activityKey: card.activityKey,
+ },
+ ]);
+ }, CARD_TTL_MS);
+
+ resultTimersRef.current.set(card.activityKey, timeout);
+ }
+
+ for (const [activityKey, timer] of resultTimersRef.current) {
+ if (selectedByKey.has(activityKey)) {
+ continue;
+ }
+
+ window.clearTimeout(timer);
+ resultTimersRef.current.delete(activityKey);
+ }
+ }, [selected]);
+
+ useEffect(() => {
+ const timers = resultTimersRef.current;
+ return () => {
+ for (const timer of timers.values()) {
+ window.clearTimeout(timer);
+ }
+ timers.clear();
+ };
+ }, []);
+
+ return (
+ <Layer name="toast">
+ <InAppAgentActivityCards
+ cards={selected}
+ onOpen={(card) => {
+ retire([card]);
+ onOpenConversation(card.conversationId);
+ }}
+ onDismiss={(card) => {
+ retire([card]);
+ }}
+ />
+ </Layer>
+ );
+}
diff --git a/web/src/features/in-app-agent/components/InAppAgentBackgroundHint.tsx b/web/src/features/in-app-agent/components/InAppAgentBackgroundHint.tsx
new file mode 100644
index 0000000000..38ed776881
--- /dev/null
+++ b/web/src/features/in-app-agent/components/InAppAgentBackgroundHint.tsx
@@ -0,0 +1,58 @@
+import { BotMessageSquare, Minus } from "lucide-react";
+
+import { Button } from "@/src/components/ui/button";
+import { KeyboardShortcut } from "@/src/components/ui/keyboard-shortcut";
+import { cn } from "@/src/utils/tailwind";
+
+/**
+ * Transient nudge that the run keeps going without the drawer. Lives in the
+ * notice band, so showing it never shifts the composer or the run indicator.
+ */
+export function InAppAgentBackgroundHint({
+ isExpanded,
+ onMinimize,
+}: {
+ isExpanded: boolean;
+ onMinimize: () => void;
+}) {
+ return (
+ <div className="shrink-0 px-2 pb-2">
+ <div className={cn(isExpanded && "mx-auto max-w-3xl")}>
+ <p
+ role="status"
+ className={cn(
+ "border-border bg-muted/60 text-foreground animate-in fade-in flex w-full items-center gap-2 rounded-lg border px-2 py-1",
+ isExpanded ? "text-sm" : "text-xs",
+ )}
+ >
+ <BotMessageSquare aria-hidden="true" className="size-3 shrink-0" />
+ <span className="min-w-0 flex-1">
+ I keep running in the background. Feel free to minimize, I&apos;ll
+ notify you when I&apos;m done or need you.
+ </span>
+ {/* Mirrors the header control, so the hint teaches the affordance. */}
+ <Button
+ type="button"
+ variant="ghost"
+ size="sm"
+ aria-label="Minimize assistant"
+ className="-my-0.5 h-5 shrink-0 gap-1 px-1"
+ onClick={onMinimize}
+ >
+ <Minus className="size-3" />
+ <KeyboardShortcut
+ className="bg-transparent shadow-none"
+ keys={[
+ typeof navigator !== "undefined" &&
+ navigator.userAgent.includes("Mac")
+ ? "⌘"
+ : "Ctrl",
+ "I",
+ ]}
+ />
+ </Button>
+ </p>
+ </div>
+ </div>
+ );
+}
diff --git a/web/src/features/in-app-agent/components/InAppAgentExecution.clienttest.tsx b/web/src/features/in-app-agent/components/InAppAgentExecution.clienttest.tsx
index a06be3ad03..73f8494c14 100644
--- a/web/src/features/in-app-agent/components/InAppAgentExecution.clienttest.tsx
+++ b/web/src/features/in-app-agent/components/InAppAgentExecution.clienttest.tsx
@@ -18,6 +18,16 @@ const providerMocks = vi.hoisted(() => {
const startRun = vi.fn();
const cancelRun = vi.fn();
const decideToolApproval = vi.fn();
+ const activityQuery = {
+ data: undefined as undefined,
+ refetch: vi.fn(() => Promise.resolve({ data: undefined })),
+ };
+ const activityUseQuery = vi.fn(
+ (
+ _input?: { projectId: string; limit: number },
+ _options?: { enabled?: boolean },
+ ) => activityQuery,
+ );
return {
capture: vi.fn(),
@@ -30,6 +40,8 @@ const providerMocks = vi.hoisted(() => {
decideToolApproval: { mutateAsync: decideToolApproval },
},
getConversation: vi.fn(),
+ activityQuery,
+ activityUseQuery,
listQuery: {
data: { pages: [{ conversations: [] }] },
error: null,
@@ -66,22 +78,22 @@ const providerMocks = vi.hoisted(() => {
},
utils: {
dashboard: {
- invalidate: vi.fn(),
+ invalidate: vi.fn(() => Promise.resolve()),
},
dashboardWidgets: {
- invalidate: vi.fn(),
+ invalidate: vi.fn(() => Promise.resolve()),
},
inAppAgent: {
getConversation: {
fetch: vi.fn(),
- invalidate: vi.fn(),
+ invalidate: vi.fn(() => Promise.resolve()),
},
listConversations: {
- invalidate: vi.fn(),
+ invalidate: vi.fn(() => Promise.resolve()),
},
},
prompts: {
- invalidate: vi.fn(),
+ invalidate: vi.fn(() => Promise.resolve()),
},
},
};
@@ -94,17 +106,34 @@ vi.mock("next/router", () => ({
}),
}));
+const sessionMocks = vi.hoisted(() => ({
+ userId: "user-1" as string | undefined,
+ aiFeaturesEnabled: true,
+ isLangfuseCloud: true,
+}));
+
vi.mock("next-auth/react", () => ({
- useSession: () => ({ data: { user: { name: "Test User" } } }),
+ useSession: () => ({
+ data: {
+ user: { id: sessionMocks.userId, name: "Test User" },
+ },
+ }),
}));
vi.mock("@/src/features/entitlements/hooks", () => ({
useHasEntitlement: () => true,
}));
+vi.mock("@/src/features/organizations/hooks", () => ({
+ useLangfuseCloudRegion: () => ({
+ isLangfuseCloud: sessionMocks.isLangfuseCloud,
+ region: sessionMocks.isLangfuseCloud ? "US" : undefined,
+ }),
+}));
+
vi.mock("@/src/features/projects/hooks", () => ({
useQueryProjectOrOrganization: () => ({
- organization: { aiFeaturesEnabled: true },
+ organization: { aiFeaturesEnabled: sessionMocks.aiFeaturesEnabled },
}),
}));
@@ -118,6 +147,11 @@ vi.mock("@/src/utils/api", () => ({
inAppAgent: {
listConversations: {
useInfiniteQuery: () => providerMocks.listQuery,
+ // Bounded activity poll: same procedure, `limit: 50`.
+ useQuery: (
+ input: { projectId: string; limit: number },
+ options?: { enabled?: boolean },
+ ) => providerMocks.activityUseQuery(input, options),
},
getConversation: {
useQuery: (...args: unknown[]) => {
@@ -240,6 +274,12 @@ function queryActivityIndicator() {
describe("in-app agent execution", () => {
beforeEach(() => {
+ sessionMocks.userId = "user-1";
+ sessionMocks.aiFeaturesEnabled = true;
+ sessionMocks.isLangfuseCloud = true;
+ providerMocks.activityUseQuery.mockImplementation(
+ () => providerMocks.activityQuery,
+ );
vi.stubGlobal(
"matchMedia",
vi.fn(() => ({
@@ -258,6 +298,35 @@ describe("in-app agent execution", () => {
window.sessionStorage.clear();
});
+ // Gated more strictly than useCanUseInAppAgent, which ignores the org AI
+ // toggle so the entry points can offer to turn it on. Polling with it off
+ // turns every page load and window focus into a Forbidden toast.
+ it("polls for activity only once AI features are on", () => {
+ sessionMocks.aiFeaturesEnabled = false;
+
+ const offRender = render(
+ <InAppAiAgentProvider defaultOpen={false}>
+ <div />
+ </InAppAiAgentProvider>,
+ );
+
+ expect(providerMocks.activityUseQuery.mock.calls.at(-1)?.[1]?.enabled).toBe(
+ false,
+ );
+ offRender.unmount();
+
+ sessionMocks.aiFeaturesEnabled = true;
+ render(
+ <InAppAiAgentProvider defaultOpen={false}>
+ <div />
+ </InAppAiAgentProvider>,
+ );
+
+ expect(providerMocks.activityUseQuery.mock.calls.at(-1)?.[1]?.enabled).toBe(
+ true,
+ );
+ });
+
it("always allows a persisted background tool for the conversation", async () => {
const approvedSnapshot = {
conversation: {
@@ -986,6 +1055,12 @@ describe("in-app agent execution", () => {
describe("in-app agent concurrent conversations", () => {
beforeEach(() => {
+ sessionMocks.userId = "user-1";
+ sessionMocks.aiFeaturesEnabled = true;
+ sessionMocks.isLangfuseCloud = true;
+ providerMocks.activityUseQuery.mockImplementation(
+ () => providerMocks.activityQuery,
+ );
vi.stubGlobal(
"matchMedia",
vi.fn(() => ({
@@ -1178,7 +1253,7 @@ describe("in-app agent concurrent conversations", () => {
expect(screen.getByText("Retry question")).toBeVisible();
expect(providerMocks.capture).toHaveBeenCalledWith(
"in_app_agent:new_chat_started",
- { entryPoint: "chat" },
+ { entryPoint: "chat", hasOtherActiveRun: false },
);
expect(
providerMocks.capture.mock.calls.filter(
diff --git a/web/src/features/in-app-agent/components/InAppAgentWindow.clienttest.tsx b/web/src/features/in-app-agent/components/InAppAgentWindow.clienttest.tsx
index eec074f762..4ea6015a4e 100644
--- a/web/src/features/in-app-agent/components/InAppAgentWindow.clienttest.tsx
+++ b/web/src/features/in-app-agent/components/InAppAgentWindow.clienttest.tsx
@@ -11,7 +11,9 @@ import { ControlledInAppAgentWindow } from "./ControlledInAppAgentWindow";
const capture = vi.fn();
const controlledAgent = vi.hoisted(() => ({
value: {
- conversations: [],
+ conversations: [] as Array<{ id: string; title: string | null }>,
+ activityByConversationId: new Map<string, { state: string }>(),
+ attentionCount: 0,
error: null,
hasMoreConversations: false,
isLoadingMoreConversations: false,
@@ -76,6 +78,7 @@ function windowElement(
) {
const props: InAppAgentWindowProps = {
conversations: [],
+ activityByConversationId: new Map(),
error: null,
executionUi: { notice: null, stop: null },
hasMoreConversations: false,
@@ -204,6 +207,43 @@ describe("InAppAgentWindow quick actions", () => {
});
});
+describe("InAppAgentWindow conversation history", () => {
+ it("counts conversations that still owe the user a look on the history trigger", () => {
+ render(
+ windowElement({
+ activityByConversationId: new Map([
+ [
+ "conversation-1",
+ {
+ activityKey: "run-1:SUCCEEDED",
+ runId: "run-1",
+ title: "Latency outliers",
+ state: "done-unread",
+ needsAttention: true,
+ },
+ ],
+ [
+ "conversation-2",
+ {
+ activityKey: "run-2:RUNNING",
+ runId: "run-2",
+ title: "Score correlation",
+ state: "running",
+ needsAttention: false,
+ },
+ ],
+ ]),
+ }),
+ );
+
+ expect(
+ screen.getByRole("button", {
+ name: "Conversation history (1 needs attention)",
+ }),
+ ).toBeInTheDocument();
+ });
+});
+
describe("ControlledInAppAgentWindow composer", () => {
beforeEach(() => {
controlledAgent.value.error = null;
@@ -272,7 +312,7 @@ describe("ControlledInAppAgentWindow composer", () => {
screen.getByRole("button", { name: "Start new conversation" }),
).toBeEnabled();
expect(
- screen.getByRole("button", { name: "Conversation history" }),
+ screen.getByRole("button", { name: /^Conversation history/ }),
).toBeEnabled();
});
@@ -298,7 +338,7 @@ describe("ControlledInAppAgentWindow composer", () => {
screen.getByRole("button", { name: "Start new conversation" }),
).toBeEnabled();
expect(
- screen.getByRole("button", { name: "Conversation history" }),
+ screen.getByRole("button", { name: /^Conversation history/ }),
).toBeEnabled();
});
});
diff --git a/web/src/features/in-app-agent/components/InAppAgentWindow.stories.tsx b/web/src/features/in-app-agent/components/InAppAgentWindow.stories.tsx
index 88848aa433..fd8e06fba6 100644
--- a/web/src/features/in-app-agent/components/InAppAgentWindow.stories.tsx
+++ b/web/src/features/in-app-agent/components/InAppAgentWindow.stories.tsx
@@ -1,6 +1,6 @@
import preview from "../../../../.storybook/preview";
import { type ReactNode, useEffect, useRef, useState } from "react";
-import { expect, fn, userEvent, waitFor, within } from "storybook/test";
+import { expect, fn, screen, userEvent, waitFor, within } from "storybook/test";
import type { AgUiMessage } from "@langfuse/shared/in-app-agent";
import {
InAppAgentWindow,
@@ -8,6 +8,7 @@ import {
type InAppAgentWindowProps,
} from "./InAppAgentWindow";
import { getInAppAgentQuickActionContext } from "@/src/features/in-app-agent/quickActions";
+import type { InAppAgentActivityByConversationId } from "@/src/features/in-app-agent/lib/inAppAgentActivity";
import {
createInAppAgentDisplayState,
projectInAppAgentMessagesForDisplay,
@@ -571,6 +572,81 @@ const conversations = [
},
];
+/**
+ * One conversation per activity state, in the priority order a row applies:
+ * only the first matching state is ever rendered.
+ */
+const activityConversations = [
+ {
+ id: "activity-approval",
+ title: "Create the eval dataset",
+ updatedAt: new Date("2026-05-19T10:00:00.000Z"),
+ },
+ {
+ id: "activity-running",
+ title: "Activity digest comparing last two weeks",
+ updatedAt: new Date("2026-05-19T09:30:00.000Z"),
+ },
+ {
+ id: "activity-failed",
+ title: "Score correlation",
+ updatedAt: new Date("2026-05-19T09:00:00.000Z"),
+ },
+ {
+ id: "activity-done",
+ title: "Latency outliers",
+ updatedAt: new Date("2026-05-19T08:30:00.000Z"),
+ },
+ {
+ id: "activity-none",
+ title: "Seed conversation",
+ updatedAt: new Date("2026-05-19T08:00:00.000Z"),
+ },
+];
+
+const activityByConversationId: InAppAgentActivityByConversationId = new Map([
+ [
+ "activity-approval",
+ {
+ state: "approval",
+ title: "Create the eval dataset",
+ runId: "run-1",
+ activityKey: "run-1:AWAITING_APPROVAL",
+ needsAttention: true,
+ },
+ ],
+ [
+ "activity-running",
+ {
+ state: "running",
+ title: "Activity digest comparing last two weeks",
+ runId: "run-2",
+ activityKey: "run-2:RUNNING",
+ needsAttention: false,
+ },
+ ],
+ [
+ "activity-failed",
+ {
+ state: "failed-unread",
+ title: "Score correlation",
+ runId: "run-3",
+ activityKey: "run-3:FAILED",
+ needsAttention: true,
+ },
+ ],
+ [
+ "activity-done",
+ {
+ state: "done-unread",
+ title: "Latency outliers",
+ runId: "run-4",
+ activityKey: "run-4:SUCCEEDED",
+ needsAttention: true,
+ },
+ ],
+]);
+
const longUnbrokenWord = `trace-${"0123456789abcdef".repeat(18)}`;
const longUnbrokenTableValue = `observation-${"abcdefghijklmnopqrstuvwxyz".repeat(10)}`;
const longReasoningText = [
@@ -601,6 +677,7 @@ const meta = preview.meta({
isConversationInteractionDisabled: false,
isSelectedConversationHydrating: false,
conversations,
+ activityByConversationId: new Map(),
hasMoreConversations: false,
isLoadingMoreConversations: false,
isAssistantTurnInProgress: false,
@@ -1003,6 +1080,106 @@ export const Error = meta.story({
},
});
+/**
+ * Every activity state in the row it belongs to, sharing one fixed-width slot
+ * so the column stays straight despite the dots being narrower than the icons.
+ *
+ * The trigger badge counts the same rows, so it reads 3 here, not 4: the
+ * running conversation has nothing for the user to act on yet.
+ */
+export const ConversationActivity = meta.story({
+ args: {
+ conversations: activityConversations,
+ activityByConversationId,
+ selectedConversationId: "activity-running",
+ messages: [],
+ },
+ play: async ({ canvasElement }: { canvasElement: HTMLElement }) => {
+ const canvas = within(canvasElement);
+
+ // Exact name (not the prefix match the activity-free stories use) so the
+ // badge count is asserted on the way in.
+ await userEvent.click(
+ canvas.getByRole("button", {
+ name: "Conversation history (3 need attention)",
+ }),
+ );
+ // The dropdown portals out of the canvas.
+ await screen.findByText("Recent conversations");
+ },
+});
+
+/** Long enough to watch the hint, short enough to settle before it expires. */
+const STORY_RUN_MS = 3_000;
+
+/**
+ * The nudge that opens a conversation. Send a second message to see that it
+ * belongs to the first one only, and wait for the run to settle to see it go.
+ */
+export const BackgroundHint = meta.story({
+ args: {
+ messages: [],
+ },
+ render: function Render(args) {
+ const [messages, setMessages] = useState<InAppAgentWindowMessage[]>([]);
+ const [isRunning, setIsRunning] = useState(false);
+
+ return (
+ <StatefulInAppAgentWindow
+ {...args}
+ messages={messages}
+ isAssistantTurnInProgress={isRunning}
+ onSubmit={(input) => {
+ setMessages((currentMessages) => [
+ ...currentMessages,
+ {
+ id: `user-${currentMessages.length}`,
+ role: "user",
+ content: { type: "text", text: input },
+ },
+ ]);
+ setIsRunning(true);
+
+ window.setTimeout(() => {
+ setIsRunning(false);
+ setMessages((currentMessages) => [
+ ...currentMessages,
+ {
+ id: `assistant-${currentMessages.length}`,
+ role: "assistant",
+ content: {
+ type: "text",
+ text: "Cost is up 12% week over week, driven by gpt-4o traces.",
+ },
+ },
+ ]);
+ }, STORY_RUN_MS);
+
+ args.onSubmit(input);
+ return true;
+ }}
+ />
+ );
+ },
+ play: async ({ canvasElement }: { canvasElement: HTMLElement }) => {
+ const canvas = within(canvasElement);
+
+ await userEvent.type(
+ canvas.getByRole("textbox", { name: "Message the assistant" }),
+ "Compare cost against last week",
+ );
+ await userEvent.click(canvas.getByRole("button", { name: "Send message" }));
+ await expect(await canvas.findByRole("status")).toHaveTextContent(
+ "I keep running in the background",
+ );
+
+ await waitFor(
+ () => expect(canvas.queryByRole("status")).not.toBeInTheDocument(),
+ { timeout: STORY_RUN_MS * 2 },
+ );
+ },
+});
+
export const BackgroundRun = meta.story({
args: {
isAssistantTurnInProgress: true,
@@ -1133,7 +1310,7 @@ export const LoadingConversation = meta.story({
canvas.getByRole("button", { name: "Start new conversation" }),
).toBeEnabled();
await expect(
- canvas.getByRole("button", { name: "Conversation history" }),
+ canvas.getByRole("button", { name: /^Conversation history/ }),
).toBeEnabled();
await expect(
canvas.getByRole("textbox", { name: "Message the assistant" }),
@@ -1213,7 +1390,7 @@ export const RateLimited = meta.story({
canvas.getByRole("button", { name: "Start new conversation" }),
).toBeEnabled();
await expect(
- canvas.getByRole("button", { name: "Conversation history" }),
+ canvas.getByRole("button", { name: /^Conversation history/ }),
).toBeEnabled();
},
});
diff --git a/web/src/features/in-app-agent/components/InAppAgentWindow.tsx b/web/src/features/in-app-agent/components/InAppAgentWindow.tsx
index af3f10b967..208a474292 100644
--- a/web/src/features/in-app-agent/components/InAppAgentWindow.tsx
+++ b/web/src/features/in-app-agent/components/InAppAgentWindow.tsx
@@ -45,6 +45,10 @@ import {
} from "./InAppAgentMessage";
import type { InAppAgentMessageFeedbackValue } from "@langfuse/shared/in-app-agent";
import type { InAppAgentScreenContextDescription } from "@/src/features/in-app-agent/context";
+import type { InAppAgentActivityByConversationId } from "@/src/features/in-app-agent/lib/inAppAgentActivity";
+import { ConversationActivityIndicator } from "@/src/features/in-app-agent/components/ConversationActivityIndicator";
+import { InAppAgentBackgroundHint } from "@/src/features/in-app-agent/components/InAppAgentBackgroundHint";
+import { useInAppAgentBackgroundHint } from "@/src/features/in-app-agent/lib/useInAppAgentBackgroundHint";
import { InAppAgentToolCallCard } from "@/src/features/in-app-agent/components/InAppAgentToolCallCard";
import {
type InAppAgentError,
@@ -267,6 +271,8 @@ export type InAppAgentWindowExecutionUi = {
export type InAppAgentWindowProps = {
conversations: InAppAgentWindowConversation[];
+ /** Per-conversation attention state, for the recent-conversation indicators. */
+ activityByConversationId: InAppAgentActivityByConversationId;
disablePendingToolApprovalActions?: boolean;
error: InAppAgentError | null;
executionUi: InAppAgentWindowExecutionUi;
@@ -371,6 +377,7 @@ function InAppAgentGenericError({
export function InAppAgentWindow(props: InAppAgentWindowProps) {
const {
+ activityByConversationId,
conversations,
disablePendingToolApprovalActions = false,
error,
@@ -430,6 +437,15 @@ export function InAppAgentWindow(props: InAppAgentWindowProps) {
const [input, setInput] = useState("");
const [isConversationHistoryOpen, setIsConversationHistoryOpen] =
useState(false);
+ // Same conversations the launcher badge counts, narrowed to the ones behind
+ // this trigger: the list is the only place to act on them.
+ const historyAttentionCount = [...activityByConversationId.values()].filter(
+ (entry) => entry.needsAttention,
+ ).length;
+ const historyAttentionSuffix =
+ historyAttentionCount > 0
+ ? ` (${historyAttentionCount} ${historyAttentionCount === 1 ? "needs" : "need"} attention)`
+ : "";
const hasUserMessage = messages.some((message) => message.role === "user");
const pendingToolCalls = messages.flatMap((message) =>
message.content.type === "toolGroup"
@@ -460,6 +476,10 @@ export function InAppAgentWindow(props: InAppAgentWindowProps) {
})
.filter((message): message is InAppAgentWindowMessage => message !== null);
+ const backgroundHint = useInAppAgentBackgroundHint({
+ isRunActive: isAssistantTurnInProgress,
+ });
+
const submitInput = (content: string, options?: InAppAgentSubmitOptions) => {
const trimmedContent = content.trim();
@@ -467,9 +487,17 @@ export function InAppAgentWindow(props: InAppAgentWindowProps) {
return;
}
+ // Read before the parent appends the message: the hint belongs to the
+ // message that opens a conversation, not to every turn inside it.
+ const startsConversation = !hasUserMessage;
+
Promise.resolve(onSubmit(trimmedContent, options))
.then((submitted) => {
if (submitted) {
+ if (startsConversation) {
+ backgroundHint.show();
+ }
+
isAutoScrollAttachedRef.current = true;
setInput((currentInput) =>
@@ -597,10 +625,24 @@ export function InAppAgentWindow(props: InAppAgentWindowProps) {
type="button"
variant="ghost"
size="icon"
- className="size-6 shrink-0"
- aria-label="Conversation history"
+ className="relative size-6 shrink-0"
+ // Count lives on the button name, as on the launcher — a
+ // nested badge aria-label is ignored once the parent has one.
+ aria-label={`Conversation history${historyAttentionSuffix}`}
>
<History className="size-3" />
+ {/* Launcher badge, scaled to the 24px trigger. Visual only —
+ accessible name is on the button. */}
+ {historyAttentionCount > 0 && (
+ <span
+ aria-hidden="true"
+ className="bg-primary-accent text-primary-foreground absolute -top-0.5 -right-0.5 flex h-3 min-w-3 items-center justify-center rounded-full px-1 text-[9px] leading-none font-bold"
+ >
+ {historyAttentionCount > 99
+ ? "99+"
+ : historyAttentionCount}
+ </span>
+ )}
</Button>
</DropdownMenuTrigger>
</TooltipTrigger>
@@ -620,6 +662,9 @@ export function InAppAgentWindow(props: InAppAgentWindowProps) {
conversations.map((conversation) => {
const conversationTitle =
conversation.title?.trim() || "Untitled conversation";
+ const activityState = activityByConversationId.get(
+ conversation.id,
+ )?.state;
return (
<DropdownMenuItem
@@ -639,15 +684,17 @@ export function InAppAgentWindow(props: InAppAgentWindowProps) {
>
{conversationTitle}
</span>
+ {activityState ? (
+ <ConversationActivityIndicator state={activityState} />
+ ) : null}
<Button
type="button"
variant="ghost"
size="icon-xs"
className="text-muted-foreground hover:text-destructive -mr-1.5 shrink-0"
- disabled={
- isConversationInteractionDisabled ||
- isAssistantTurnInProgress
- }
+ // Deleting is always allowed; it cancels whatever the
+ // conversation was doing rather than refusing.
+ disabled={isConversationInteractionDisabled}
aria-label="Delete conversation"
onClick={(event) => {
event.preventDefault();
@@ -936,6 +983,15 @@ export function InAppAgentWindow(props: InAppAgentWindowProps) {
</div>
</div>
) : null}
+ {backgroundHint.isVisible && props.onClose ? (
+ <InAppAgentBackgroundHint
+ isExpanded={isExpanded}
+ onMinimize={() => {
+ backgroundHint.hide();
+ props.onClose?.();
+ }}
+ />
+ ) : null}
{error?.type === "rate_limit" && (
<div
className={cn(
diff --git a/web/src/features/in-app-agent/components/InAppAiAgentProvider.tsx b/web/src/features/in-app-agent/components/InAppAiAgentProvider.tsx
index 745014c71f..d44bac23b7 100644
--- a/web/src/features/in-app-agent/components/InAppAiAgentProvider.tsx
+++ b/web/src/features/in-app-agent/components/InAppAiAgentProvider.tsx
@@ -37,6 +37,12 @@ import {
projectInAppAgentMessagesForDisplay,
type InAppAgentDisplayState,
} from "@/src/features/in-app-agent/lib/display";
+import { useInAppAgentActivity } from "@/src/features/in-app-agent/lib/useInAppAgentActivity";
+import {
+ getInAppAgentPendingNotificationCards,
+ type InAppAgentActivityByConversationId,
+} from "@/src/features/in-app-agent/lib/inAppAgentActivity";
+import { InAppAgentActivityNotifications } from "@/src/features/in-app-agent/components/InAppAgentActivityNotifications";
import { InAppAgentBackgroundClient } from "@/src/features/in-app-agent/lib/backgroundAgentClient";
import {
BackgroundExecutionSessionController,
@@ -135,6 +141,8 @@ const NOOP_CONTEXT: InAppAiAgentContextType = {
conversations: [],
hasMoreConversations: false,
isLoadingMoreConversations: false,
+ activityByConversationId: new Map(),
+ attentionCount: 0,
selectedConversationId: undefined,
selectedConversationIsWriteLocked: false,
loadMoreConversations: () => undefined,
@@ -192,6 +200,10 @@ type InAppAiAgentContextType = {
conversations: InAppAiAgentConversation[];
hasMoreConversations: boolean;
isLoadingMoreConversations: boolean;
+ /** Conversations wanting attention, by id. */
+ activityByConversationId: InAppAgentActivityByConversationId;
+ /** Conversations the user still owes a look, for the launcher badge. */
+ attentionCount: number;
selectedConversationId: string | undefined;
selectedConversationIsWriteLocked: boolean;
loadMoreConversations: () => void;
@@ -251,14 +263,20 @@ function InAppAiAgentProjectProvider({
}: InAppAiAgentProviderProps & {
projectId: string;
}) {
+ const session = useSession();
+ const userId = session.data?.user?.id ?? null;
const [open, setOpen] = useSessionStorage<boolean>(
`${OPEN_STORAGE_KEY_PREFIX}:${projectId}`,
defaultOpen ?? false,
);
+ // Remount when userId resolves so activity localStorage re-reads the
+ // user-scoped ledger key (useLocalStorage only loads on mount).
return (
<InAppAiAgentProviderInner
+ key={userId ?? "pending-session"}
projectId={projectId}
+ userId={userId}
open={open}
setOpen={setOpen}
>
@@ -269,6 +287,7 @@ function InAppAiAgentProjectProvider({
type InAppAiAgentProviderInnerProps = PropsWithChildren<{
projectId: string;
+ userId: string | null;
open: boolean;
setOpen: Dispatch<SetStateAction<boolean>>;
}>;
@@ -276,12 +295,14 @@ type InAppAiAgentProviderInnerProps = PropsWithChildren<{
function InAppAiAgentProviderInner({
children,
projectId,
+ userId,
open,
setOpen,
}: InAppAiAgentProviderInnerProps) {
const utils = api.useUtils();
const capture = usePostHogClientCapture();
const session = useSession();
+ const isInAppAgentEnabled = useIsInAppAgentEnabled();
const { organization } = useQueryProjectOrOrganization();
const [enableDialogOpen, setEnableDialogOpen] = useState(false);
const [_selectedConversationId, setSelectedConversationId] =
@@ -414,6 +435,24 @@ function InAppAiAgentProviderInner({
: error;
const liveMessageVersion = backgroundExecutionView.liveMessageRevision;
+ const {
+ activityByConversationId,
+ attentionCount,
+ delivered,
+ refetchActivity,
+ markConversationHandled,
+ markDelivered,
+ } = useInAppAgentActivity({
+ projectId,
+ userId,
+ // Polling a project the server will reject turns every page load and
+ // window focus into a Forbidden toast.
+ enabled: isInAppAgentEnabled,
+ // Only what the user can actually see counts as looked at; a selected
+ // conversation behind a closed window has not been read.
+ visibleConversationId: open ? selectedConversationId : null,
+ });
+
const effectivePendingToolApprovals = useMemo(() => {
return backgroundExecutionView.pendingToolApprovals.map(
({ runId, approvalRequest, status }): InAppAgentPendingToolApproval => ({
@@ -552,10 +591,12 @@ function InAppAiAgentProviderInner({
hasMoreConversations,
isLoadingMoreConversations,
]);
- const invalidateConversations = useCallback(
- () => utils.inAppAgent.listConversations.invalidate({ projectId }),
- [projectId, utils.inAppAgent.listConversations],
- );
+ const invalidateConversations = useCallback(() => {
+ Promise.resolve(
+ utils.inAppAgent.listConversations.invalidate({ projectId }),
+ ).catch(() => undefined);
+ Promise.resolve(refetchActivity()).catch(() => undefined);
+ }, [projectId, refetchActivity, utils.inAppAgent.listConversations]);
useEffect(() => {
if (!conversationListQuery.error) {
@@ -763,6 +804,7 @@ function InAppAiAgentProviderInner({
next.delete(started.conversationId);
return next;
});
+ Promise.resolve(refetchActivity()).catch(() => undefined);
return started;
},
});
@@ -839,11 +881,16 @@ function InAppAiAgentProviderInner({
},
onSettled: () => {
clearLoadingEvents();
- utils.inAppAgent.listConversations.invalidate({ projectId });
- utils.inAppAgent.getConversation.invalidate({
- projectId,
- conversationId,
- });
+ Promise.resolve(
+ utils.inAppAgent.listConversations.invalidate({ projectId }),
+ ).catch(() => undefined);
+ Promise.resolve(
+ utils.inAppAgent.getConversation.invalidate({
+ projectId,
+ conversationId,
+ }),
+ ).catch(() => undefined);
+ Promise.resolve(refetchActivity()).catch(() => undefined);
releaseSubmitLock(conversationId);
},
});
@@ -858,6 +905,7 @@ function InAppAiAgentProviderInner({
conversationQuery.data,
decideToolApprovalMutation,
projectId,
+ refetchActivity,
releaseSubmitLock,
resetAgent,
sharedAgentSubscriber,
@@ -909,9 +957,19 @@ function InAppAiAgentProviderInner({
releaseSubmitLock(_selectedConversationId);
resetAgent();
setSelectedConversationId(conversationId);
+
+ if (conversationId && open) {
+ const entry = activityByConversationId.get(conversationId);
+ if (entry?.needsAttention) {
+ markConversationHandled(conversationId, entry.activityKey);
+ }
+ }
},
[
_selectedConversationId,
+ activityByConversationId,
+ markConversationHandled,
+ open,
releaseSubmitLock,
resetAgent,
setSelectedConversationId,
@@ -920,10 +978,6 @@ function InAppAiAgentProviderInner({
const deleteConversation = useCallback(
async (conversationId: string) => {
- if (isRunning) {
- return;
- }
-
try {
await deleteConversationMutation.mutateAsync({
projectId,
@@ -961,7 +1015,6 @@ function InAppAiAgentProviderInner({
},
[
deleteConversationMutation,
- isRunning,
projectId,
resetAgent,
selectedConversationId,
@@ -1050,7 +1103,15 @@ function InAppAiAgentProviderInner({
agent.addMessage(userMessage);
const entryPoint = options?.entryPoint ?? "chat";
if (startsNewConversation) {
- capture("in_app_agent:new_chat_started", { entryPoint });
+ capture("in_app_agent:new_chat_started", {
+ entryPoint,
+ // Whether starting here means running two conversations at once.
+ hasOtherActiveRun: [...activityByConversationId.entries()].some(
+ ([otherId, activity]) =>
+ otherId !== conversationId &&
+ (activity.state === "running" || activity.state === "approval"),
+ ),
+ });
}
capture("in_app_agent:new_chat_turn", { entryPoint });
startedRun = true;
@@ -1079,6 +1140,7 @@ function InAppAiAgentProviderInner({
}
},
[
+ activityByConversationId,
conversationQuery.data,
capture,
clearLoadingEvents,
@@ -1371,6 +1433,30 @@ function InAppAiAgentProviderInner({
[cancelRun, currentBackgroundRun, isCancellingRun],
);
+ /** Only outcomes and questions surface as cards; a run in progress is not news. */
+ const activityNotifications = useMemo(
+ () =>
+ getInAppAgentPendingNotificationCards({
+ activityByConversationId,
+ delivered,
+ }),
+ [activityByConversationId, delivered],
+ );
+
+ const openConversationFromActivity = useCallback(
+ (conversationId: string) => {
+ const state = activityByConversationId.get(conversationId)?.state;
+
+ capture("in_app_agent:activity_opened", {
+ source: "notification",
+ activityType: state ?? "unknown",
+ });
+ setAgentOpen(true);
+ selectConversation(conversationId);
+ },
+ [activityByConversationId, capture, selectConversation, setAgentOpen],
+ );
+
const approveToolCall = useCallback(
(approvalId: string) => resumeToolApproval(approvalId, true),
[resumeToolApproval],
@@ -1408,6 +1494,8 @@ function InAppAiAgentProviderInner({
conversations,
hasMoreConversations,
isLoadingMoreConversations,
+ activityByConversationId,
+ attentionCount,
selectedConversationId: selectedConversationId ?? undefined,
selectedConversationIsWriteLocked,
loadMoreConversations,
@@ -1421,7 +1509,9 @@ function InAppAiAgentProviderInner({
submitFeedback,
}),
[
+ activityByConversationId,
approveToolCall,
+ attentionCount,
alwaysAllowToolCall,
isExpanded,
conversations,
@@ -1454,6 +1544,13 @@ function InAppAiAgentProviderInner({
return (
<InAppAiAgentContext.Provider value={value}>
{children}
+ {/* Rendered here, not from the window host, which unmounts when the
+ assistant is closed — exactly when a notification matters most. */}
+ <InAppAgentActivityNotifications
+ notifications={activityNotifications}
+ onDelivered={markDelivered}
+ onOpenConversation={openConversationFromActivity}
+ />
<InAppAgentDisabledDialog
open={enableDialogOpen}
onOpenChange={setEnableDialogOpen}
@@ -1537,8 +1634,24 @@ export function useInAppAiAgent() {
return ctx;
}
-/** Whether the current user/context may use the in-app assistant at all.
- * Shared gate for the launcher button and the window host. */
+/** Client mirror of the server's assertInAppAgentAvailable: whether a request
+ * for this project would be served, so callers can skip ones it would reject. */
+export function useIsInAppAgentEnabled() {
+ const hasInAppAgentEntitlement = useHasEntitlement("in-app-agent");
+ const { isLangfuseCloud } = useLangfuseCloudRegion();
+ const { organization } = useQueryProjectOrOrganization();
+
+ return (
+ isLangfuseCloud &&
+ hasInAppAgentEntitlement &&
+ Boolean(organization?.aiFeaturesEnabled)
+ );
+}
+
+/** Whether the current user/context may use the in-app assistant at all. Shared
+ * gate for the launcher button and the window host. Deliberately looser than
+ * useIsInAppAgentEnabled: with the org AI toggle off the entry points still
+ * show, and clicking one opens the dialog that turns it on. */
export function useCanUseInAppAgent() {
const { isAvailable } = useInAppAiAgent();
const hasInAppAgentEntitlement = useHasEntitlement("in-app-agent");
diff --git a/web/src/features/in-app-agent/lib/inAppAgentActivity.clienttest.ts b/web/src/features/in-app-agent/lib/inAppAgentActivity.clienttest.ts
new file mode 100644
index 0000000000..182a35a6b7
--- /dev/null
+++ b/web/src/features/in-app-agent/lib/inAppAgentActivity.clienttest.ts
@@ -0,0 +1,268 @@
+import { describe, expect, it } from "vitest";
+
+import { InAppAgentRunStatus } from "@langfuse/shared";
+
+import {
+ getInAppAgentActivityKey,
+ getInAppAgentPendingNotificationCards,
+ hasInFlightInAppAgentActivity,
+ markInAppAgentActivityDelivered,
+ markInAppAgentConversationHandled,
+ mergeInAppAgentReceipts,
+ reconcileInAppAgentActivity,
+ type InAppAgentActivityConversation,
+ type InAppAgentActivityReceipts,
+ type InAppAgentConversationLatestRun,
+} from "./inAppAgentActivity";
+
+const latestRun = (
+ overrides: Partial<InAppAgentConversationLatestRun> &
+ Pick<InAppAgentConversationLatestRun, "id" | "status">,
+): InAppAgentConversationLatestRun => ({
+ errorCode: null,
+ cancelRequested: false,
+ ...overrides,
+});
+
+const conversation = (
+ id: string,
+ run: InAppAgentConversationLatestRun | null,
+ title: string | null = id,
+): InAppAgentActivityConversation => ({
+ id,
+ title,
+ latestRun: run,
+});
+
+/** One poll as the hook applies it: reconcile, then record what it returned. */
+const sync = (
+ receipts: InAppAgentActivityReceipts,
+ conversations: InAppAgentActivityConversation[],
+ visibleConversationId?: string | null,
+) => {
+ const reconciled = reconcileInAppAgentActivity({
+ receipts,
+ conversations,
+ visibleConversationId,
+ });
+
+ return {
+ ...reconciled,
+ receipts: mergeInAppAgentReceipts(receipts, reconciled.acknowledgements),
+ };
+};
+
+describe("in-app agent activity receipts", () => {
+ it("baselines history, then treats status changes as unread attention", () => {
+ const first = sync(null, [
+ conversation(
+ "old",
+ latestRun({ id: "old-run", status: InAppAgentRunStatus.SUCCEEDED }),
+ ),
+ conversation(
+ "live",
+ latestRun({ id: "live-run", status: InAppAgentRunStatus.RUNNING }),
+ ),
+ conversation(
+ "parked",
+ latestRun({
+ id: "parked-run",
+ status: InAppAgentRunStatus.AWAITING_APPROVAL,
+ }),
+ ),
+ ]);
+
+ // Existing terminals and approvals are quiet after baseline…
+ expect(first.activityByConversationId.get("old")).toBeUndefined();
+ expect(first.activityByConversationId.get("parked")).toMatchObject({
+ state: "approval",
+ needsAttention: false,
+ });
+ expect(first.attentionCount).toBe(0);
+ // …while an in-flight run still shows in the list.
+ expect(first.activityByConversationId.get("live")?.state).toBe("running");
+
+ const afterCompletion = sync(first.receipts, [
+ conversation(
+ "old",
+ latestRun({ id: "old-run", status: InAppAgentRunStatus.SUCCEEDED }),
+ ),
+ conversation(
+ "live",
+ latestRun({ id: "live-run", status: InAppAgentRunStatus.SUCCEEDED }),
+ ),
+ conversation(
+ "parked",
+ latestRun({
+ id: "parked-run",
+ status: InAppAgentRunStatus.AWAITING_APPROVAL,
+ }),
+ ),
+ ]);
+
+ expect(afterCompletion.activityByConversationId.get("live")).toMatchObject({
+ state: "done-unread",
+ needsAttention: true,
+ });
+ expect(afterCompletion.attentionCount).toBe(1);
+ });
+
+ it("clears badge attention when seen but keeps list approval status", () => {
+ const running = sync(null, [
+ conversation(
+ "approve",
+ latestRun({ id: "approve-run", status: InAppAgentRunStatus.RUNNING }),
+ ),
+ ]);
+
+ const needsApproval = sync(running.receipts, [
+ conversation(
+ "approve",
+ latestRun({
+ id: "approve-run",
+ status: InAppAgentRunStatus.AWAITING_APPROVAL,
+ }),
+ ),
+ ]);
+
+ expect(needsApproval.activityByConversationId.get("approve")).toMatchObject(
+ {
+ state: "approval",
+ needsAttention: true,
+ },
+ );
+ expect(needsApproval.attentionCount).toBe(1);
+ expect(
+ getInAppAgentPendingNotificationCards({
+ activityByConversationId: needsApproval.activityByConversationId,
+ delivered: null,
+ }),
+ ).toHaveLength(1);
+
+ const seen = sync(
+ needsApproval.receipts,
+ [
+ conversation(
+ "approve",
+ latestRun({
+ id: "approve-run",
+ status: InAppAgentRunStatus.AWAITING_APPROVAL,
+ }),
+ ),
+ ],
+ "approve",
+ );
+
+ expect(seen.activityByConversationId.get("approve")).toMatchObject({
+ state: "approval",
+ needsAttention: false,
+ });
+ expect(seen.attentionCount).toBe(0);
+ expect(
+ getInAppAgentPendingNotificationCards({
+ activityByConversationId: seen.activityByConversationId,
+ delivered: null,
+ }),
+ ).toEqual([]);
+ });
+
+ it("keeps delivered toasts independent from unread receipts", () => {
+ const unread = sync(null, [
+ conversation(
+ "c1",
+ latestRun({ id: "run-1", status: InAppAgentRunStatus.RUNNING }),
+ ),
+ ]);
+ const finished = sync(unread.receipts, [
+ conversation(
+ "c1",
+ latestRun({ id: "run-1", status: InAppAgentRunStatus.SUCCEEDED }),
+ "Latency",
+ ),
+ ]);
+
+ const activityKey = getInAppAgentActivityKey({
+ id: "run-1",
+ status: InAppAgentRunStatus.SUCCEEDED,
+ });
+ expect(
+ getInAppAgentPendingNotificationCards({
+ activityByConversationId: finished.activityByConversationId,
+ delivered: null,
+ }),
+ ).toEqual([
+ expect.objectContaining({
+ conversationId: "c1",
+ activityKey,
+ state: "done-unread",
+ }),
+ ]);
+
+ const delivered = markInAppAgentActivityDelivered(null, [
+ { conversationId: "c1", activityKey },
+ ]);
+ expect(
+ getInAppAgentPendingNotificationCards({
+ activityByConversationId: finished.activityByConversationId,
+ delivered,
+ }),
+ ).toEqual([]);
+ // Dismissing the toast does not clear badge attention.
+ expect(finished.activityByConversationId.get("c1")).toMatchObject({
+ state: "done-unread",
+ needsAttention: true,
+ });
+ expect(finished.attentionCount).toBe(1);
+
+ const handled = markInAppAgentConversationHandled(
+ finished.receipts,
+ "c1",
+ activityKey,
+ );
+ const afterOpen = sync(handled, [
+ conversation(
+ "c1",
+ latestRun({ id: "run-1", status: InAppAgentRunStatus.SUCCEEDED }),
+ ),
+ ]);
+ expect(afterOpen.activityByConversationId.get("c1")).toBeUndefined();
+ expect(afterOpen.attentionCount).toBe(0);
+ });
+
+ it("keeps the activity poll alive only while a run is still executing", () => {
+ expect(
+ hasInFlightInAppAgentActivity([
+ conversation(
+ "parked",
+ latestRun({
+ id: "parked-run",
+ status: InAppAgentRunStatus.AWAITING_APPROVAL,
+ }),
+ ),
+ ]),
+ ).toBe(false);
+ expect(
+ hasInFlightInAppAgentActivity([
+ conversation(
+ "queued",
+ latestRun({ id: "queued-run", status: InAppAgentRunStatus.QUEUED }),
+ ),
+ ]),
+ ).toBe(true);
+ expect(
+ hasInFlightInAppAgentActivity([
+ conversation(
+ "live",
+ latestRun({ id: "live-run", status: InAppAgentRunStatus.RUNNING }),
+ ),
+ conversation(
+ "parked",
+ latestRun({
+ id: "parked-run",
+ status: InAppAgentRunStatus.AWAITING_APPROVAL,
+ }),
+ ),
+ ]),
+ ).toBe(true);
+ });
+});
diff --git a/web/src/features/in-app-agent/lib/inAppAgentActivity.ts b/web/src/features/in-app-agent/lib/inAppAgentActivity.ts
new file mode 100644
index 0000000000..41dd151f00
--- /dev/null
+++ b/web/src/features/in-app-agent/lib/inAppAgentActivity.ts
@@ -0,0 +1,388 @@
+import { InAppAgentRunStatus } from "@langfuse/shared";
+import { isUnsettledInAppAgentRunStatus } from "@langfuse/shared/in-app-agent";
+
+export type InAppAgentActivityState =
+ | "running"
+ | "approval"
+ | "failed-unread"
+ | "done-unread";
+
+export type InAppAgentConversationLatestRun = {
+ id: string;
+ status: InAppAgentRunStatus;
+ errorCode: string | null;
+ cancelRequested: boolean;
+};
+
+export type InAppAgentActivityConversation = {
+ id: string;
+ title: string | null;
+ latestRun: InAppAgentConversationLatestRun | null;
+};
+
+/** `null` means this device has never baselined the project's activity. */
+export type InAppAgentActivityReceipts = {
+ v: 1;
+ handled: Record<string, string>;
+} | null;
+
+export type InAppAgentDeliveredReceipts = {
+ v: 1;
+ delivered: Record<string, string>;
+} | null;
+
+/** A conversation's activity the user has now seen. */
+export type InAppAgentActivityAcknowledgement = {
+ conversationId: string;
+ activityKey: string;
+};
+
+export type InAppAgentActivityEntry = {
+ activityKey: string;
+ runId: string;
+ title: string | null;
+ /** Row / status indicator (approvals stay while the run still needs a decision). */
+ state: InAppAgentActivityState;
+ /** Badge + toast attention; false after the user has looked at this activity key. */
+ needsAttention: boolean;
+};
+
+export type InAppAgentActivityByConversationId = Map<
+ string,
+ InAppAgentActivityEntry
+>;
+
+export const IN_APP_AGENT_ACTIVITY_RECEIPTS_VERSION = 1;
+export const IN_APP_AGENT_DELIVERED_RECEIPTS_VERSION = 1;
+
+/**
+ * Activity polls the newest N conversations only (same page as the drawer list
+ * head). Accepted scope: a quieter conversation that falls outside this window
+ * will not contribute badge/toast attention until it is bumped back into the
+ * page (e.g. by a new message). Revisit if parked approvals must never drop off.
+ *
+ * Handled/delivered receipts are localStorage per browser profile per user —
+ * not synced across devices or accounts. A new profile/user baselines the
+ * current newest-N as already seen.
+ */
+export const IN_APP_AGENT_ACTIVITY_LIST_LIMIT = 50;
+
+export function getInAppAgentActivityReceiptsStorageKey(
+ projectId: string,
+ userId: string,
+) {
+ return `langfuse-in-app-agent-activity:v${IN_APP_AGENT_ACTIVITY_RECEIPTS_VERSION}:${projectId}:${userId}`;
+}
+
+export function getInAppAgentDeliveredReceiptsStorageKey(
+ projectId: string,
+ userId: string,
+) {
+ return `langfuse-in-app-agent-delivered:v${IN_APP_AGENT_DELIVERED_RECEIPTS_VERSION}:${projectId}:${userId}`;
+}
+
+export function getInAppAgentActivityKey(run: {
+ id: string;
+ status: InAppAgentRunStatus;
+}): string {
+ return `${run.id}:${run.status}`;
+}
+
+/**
+ * Derive list state + whether it still owes a badge/toast.
+ * Approvals keep list status after being seen; terminals drop out once handled.
+ */
+function getActivityEntry(params: {
+ run: InAppAgentConversationLatestRun;
+ title: string | null;
+ isHandled: boolean;
+}): InAppAgentActivityEntry | null {
+ const activityKey = getInAppAgentActivityKey(params.run);
+
+ if (params.run.status === InAppAgentRunStatus.AWAITING_APPROVAL) {
+ return {
+ activityKey,
+ runId: params.run.id,
+ title: params.title,
+ state: "approval",
+ needsAttention: !params.isHandled,
+ };
+ }
+
+ if (isUnsettledInAppAgentRunStatus(params.run.status)) {
+ return {
+ activityKey,
+ runId: params.run.id,
+ title: params.title,
+ state: "running",
+ needsAttention: false,
+ };
+ }
+
+ if (params.run.status === InAppAgentRunStatus.CANCELLED || params.isHandled) {
+ return null;
+ }
+
+ return {
+ activityKey,
+ runId: params.run.id,
+ title: params.title,
+ state:
+ params.run.status === InAppAgentRunStatus.FAILED
+ ? "failed-unread"
+ : "done-unread",
+ needsAttention: true,
+ };
+}
+
+/** Drop ledger keys for conversations no longer in the activity window. */
+export function pruneInAppAgentReceiptRecord(
+ record: Record<string, string>,
+ liveConversationIds: ReadonlySet<string>,
+): { record: Record<string, string>; changed: boolean } {
+ let changed = false;
+ const next: Record<string, string> = {};
+
+ for (const [conversationId, activityKey] of Object.entries(record)) {
+ if (!liveConversationIds.has(conversationId)) {
+ changed = true;
+ continue;
+ }
+ next[conversationId] = activityKey;
+ }
+
+ return { record: changed ? next : record, changed };
+}
+
+export function pruneInAppAgentDeliveredReceipts(
+ delivered: InAppAgentDeliveredReceipts,
+ liveConversationIds: ReadonlySet<string>,
+): InAppAgentDeliveredReceipts {
+ if (!delivered) {
+ return delivered;
+ }
+
+ const pruned = pruneInAppAgentReceiptRecord(
+ delivered.delivered,
+ liveConversationIds,
+ );
+ if (!pruned.changed) {
+ return delivered;
+ }
+
+ return {
+ v: IN_APP_AGENT_DELIVERED_RECEIPTS_VERSION,
+ delivered: pruned.record,
+ };
+}
+
+/**
+ * An in-flight run can still be acknowledged by a tab whose poll froze before
+ * the run settled, so only keys that can badge are worth recording.
+ */
+function isBadgeWorthyStatus(status: InAppAgentRunStatus): boolean {
+ return (
+ status === InAppAgentRunStatus.AWAITING_APPROVAL ||
+ !isUnsettledInAppAgentRunStatus(status)
+ );
+}
+
+/**
+ * Read list summaries into UI state plus the receipts the caller should record.
+ * Never returns a ledger: every tab shares one, so a tab that restates entries
+ * it did not author can revert another tab's read receipt.
+ */
+export function reconcileInAppAgentActivity(params: {
+ receipts: InAppAgentActivityReceipts;
+ conversations: readonly InAppAgentActivityConversation[];
+ visibleConversationId?: string | null;
+}): {
+ acknowledgements: InAppAgentActivityAcknowledgement[];
+ activityByConversationId: InAppAgentActivityByConversationId;
+ attentionCount: number;
+} {
+ const isFirstSync = params.receipts === null;
+ const handled = params.receipts?.handled ?? {};
+ const acknowledgements: InAppAgentActivityAcknowledgement[] = [];
+ const acknowledgedKeys = new Map<string, string>();
+
+ for (const conversation of params.conversations) {
+ const run = conversation.latestRun;
+ if (!run) {
+ continue;
+ }
+
+ const activityKey = getInAppAgentActivityKey(run);
+ const isVisible = params.visibleConversationId === conversation.id;
+
+ // Baseline on first sync, then ack only what the user is looking at.
+ if (
+ (isFirstSync || isVisible) &&
+ isBadgeWorthyStatus(run.status) &&
+ handled[conversation.id] !== activityKey
+ ) {
+ acknowledgements.push({ conversationId: conversation.id, activityKey });
+ acknowledgedKeys.set(conversation.id, activityKey);
+ }
+ }
+
+ const activityByConversationId: InAppAgentActivityByConversationId =
+ new Map();
+ let attentionCount = 0;
+
+ for (const conversation of params.conversations) {
+ const run = conversation.latestRun;
+ if (!run) {
+ continue;
+ }
+
+ const activityKey = getInAppAgentActivityKey(run);
+ const entry = getActivityEntry({
+ run,
+ title: conversation.title,
+ isHandled:
+ handled[conversation.id] === activityKey ||
+ acknowledgedKeys.get(conversation.id) === activityKey,
+ });
+
+ if (!entry) {
+ continue;
+ }
+
+ activityByConversationId.set(conversation.id, entry);
+ if (entry.needsAttention) {
+ attentionCount += 1;
+ }
+ }
+
+ return { acknowledgements, activityByConversationId, attentionCount };
+}
+
+/**
+ * Record acknowledgements key by key. Returns the same reference when they are
+ * all already present so callers can write during render without looping.
+ */
+export function mergeInAppAgentReceipts(
+ receipts: InAppAgentActivityReceipts,
+ acknowledgements: readonly InAppAgentActivityAcknowledgement[],
+): InAppAgentActivityReceipts {
+ // A null ledger has never been baselined, so it must be written even when
+ // this sync had nothing to acknowledge — otherwise every later sync counts
+ // as the first one and keeps marking new activity as already seen.
+ let changed = receipts === null;
+ const next = { ...(receipts?.handled ?? {}) };
+
+ for (const acknowledgement of acknowledgements) {
+ if (next[acknowledgement.conversationId] !== acknowledgement.activityKey) {
+ next[acknowledgement.conversationId] = acknowledgement.activityKey;
+ changed = true;
+ }
+ }
+
+ return changed
+ ? { v: IN_APP_AGENT_ACTIVITY_RECEIPTS_VERSION, handled: next }
+ : receipts;
+}
+
+/** Drop ledger keys for conversations no longer in the activity window. */
+export function pruneInAppAgentReceipts(
+ receipts: InAppAgentActivityReceipts,
+ liveConversationIds: ReadonlySet<string>,
+): InAppAgentActivityReceipts {
+ if (!receipts) {
+ return receipts;
+ }
+
+ const pruned = pruneInAppAgentReceiptRecord(
+ receipts.handled,
+ liveConversationIds,
+ );
+ if (!pruned.changed) {
+ return receipts;
+ }
+
+ return {
+ v: IN_APP_AGENT_ACTIVITY_RECEIPTS_VERSION,
+ handled: pruned.record,
+ };
+}
+
+export function markInAppAgentConversationHandled(
+ receipts: InAppAgentActivityReceipts,
+ conversationId: string,
+ activityKey: string,
+): InAppAgentActivityReceipts {
+ if (!receipts || receipts.handled[conversationId] === activityKey) {
+ return receipts;
+ }
+
+ return {
+ ...receipts,
+ handled: { ...receipts.handled, [conversationId]: activityKey },
+ };
+}
+
+export function markInAppAgentActivityDelivered(
+ delivered: InAppAgentDeliveredReceipts,
+ entries: ReadonlyArray<{ conversationId: string; activityKey: string }>,
+): InAppAgentDeliveredReceipts {
+ const current = delivered?.delivered ?? {};
+ let changed = delivered === null;
+ const next = { ...current };
+
+ for (const entry of entries) {
+ if (next[entry.conversationId] !== entry.activityKey) {
+ next[entry.conversationId] = entry.activityKey;
+ changed = true;
+ }
+ }
+
+ return changed
+ ? { v: IN_APP_AGENT_DELIVERED_RECEIPTS_VERSION, delivered: next }
+ : delivered;
+}
+
+export function getInAppAgentPendingNotificationCards(params: {
+ activityByConversationId: InAppAgentActivityByConversationId;
+ delivered: InAppAgentDeliveredReceipts;
+}): Array<{
+ conversationId: string;
+ activityKey: string;
+ runId: string;
+ title: string | null;
+ state: Exclude<InAppAgentActivityState, "running">;
+}> {
+ return [...params.activityByConversationId.entries()].flatMap(
+ ([conversationId, entry]) =>
+ !entry.needsAttention ||
+ entry.state === "running" ||
+ params.delivered?.delivered[conversationId] === entry.activityKey
+ ? []
+ : [
+ {
+ conversationId,
+ activityKey: entry.activityKey,
+ runId: entry.runId,
+ title: entry.title,
+ state: entry.state,
+ },
+ ],
+ );
+}
+
+/**
+ * The activity poll only needs to tick while the server can still change a
+ * run on its own. Parked approvals wait on the user; `refetchOnWindowFocus`
+ * is enough if another tab decides them.
+ */
+export function hasInFlightInAppAgentActivity(
+ conversations: readonly InAppAgentActivityConversation[],
+): boolean {
+ return conversations.some((conversation) => {
+ const status = conversation.latestRun?.status;
+ return (
+ status === InAppAgentRunStatus.QUEUED ||
+ status === InAppAgentRunStatus.RUNNING
+ );
+ });
+}
diff --git a/web/src/features/in-app-agent/lib/useInAppAgentActivity.clienttest.tsx b/web/src/features/in-app-agent/lib/useInAppAgentActivity.clienttest.tsx
new file mode 100644
index 0000000000..f06ac83b89
--- /dev/null
+++ b/web/src/features/in-app-agent/lib/useInAppAgentActivity.clienttest.tsx
@@ -0,0 +1,155 @@
+import { render, screen } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { InAppAgentRunStatus } from "@langfuse/shared";
+
+import {
+ getInAppAgentActivityReceiptsStorageKey,
+ getInAppAgentDeliveredReceiptsStorageKey,
+ type InAppAgentActivityConversation,
+} from "./inAppAgentActivity";
+import { useInAppAgentActivity } from "./useInAppAgentActivity";
+
+const PROJECT_ID = "project-1";
+const USER_ID = "user-1";
+const RECEIPTS_KEY = getInAppAgentActivityReceiptsStorageKey(
+ PROJECT_ID,
+ USER_ID,
+);
+const DELIVERED_KEY = getInAppAgentDeliveredReceiptsStorageKey(
+ PROJECT_ID,
+ USER_ID,
+);
+
+const activityMocks = vi.hoisted(() => ({
+ conversations: [] as unknown[],
+}));
+
+vi.mock("@/src/utils/api", () => ({
+ api: {
+ inAppAgent: {
+ listConversations: {
+ useQuery: () => ({
+ data: { conversations: activityMocks.conversations },
+ refetch: vi.fn(() => Promise.resolve({ data: undefined })),
+ }),
+ },
+ },
+ },
+}));
+
+const conversation = (
+ id: string,
+ status: InAppAgentRunStatus,
+ runId = `${id}-run`,
+): InAppAgentActivityConversation => ({
+ id,
+ title: id,
+ latestRun: { id: runId, status, errorCode: null, cancelRequested: false },
+});
+
+/** The tab under test. Badge attention is all the nav renders. */
+function ActivityProbe({
+ visibleConversationId,
+}: {
+ visibleConversationId: string | null;
+}) {
+ const activity = useInAppAgentActivity({
+ projectId: PROJECT_ID,
+ userId: USER_ID,
+ enabled: true,
+ visibleConversationId,
+ });
+
+ return <span data-testid="attention">{activity.attentionCount}</span>;
+}
+
+/** Receipts another tab already recorded in the ledgers every tab shares. */
+function seedLedgers(keys: Record<string, string>) {
+ localStorage.setItem(RECEIPTS_KEY, JSON.stringify({ v: 1, handled: keys }));
+ localStorage.setItem(
+ DELIVERED_KEY,
+ JSON.stringify({ v: 1, delivered: keys }),
+ );
+}
+
+function storedKeys(
+ storageKey: string,
+ field: "handled" | "delivered",
+): Record<string, string> | undefined {
+ const raw = localStorage.getItem(storageKey);
+ return raw
+ ? (JSON.parse(raw) as Record<typeof field, Record<string, string>>)[field]
+ : undefined;
+}
+
+function attention(): string | null {
+ return screen.getByTestId("attention").textContent;
+}
+
+describe("useInAppAgentActivity across tabs", () => {
+ beforeEach(() => {
+ localStorage.clear();
+ activityMocks.conversations = [];
+ });
+
+ it("does not walk a read receipt back to the run it was looking at mid-flight", () => {
+ seedLedgers({ c1: "c1-run:SUCCEEDED" });
+ // This tab's poll froze while the run was still working.
+ activityMocks.conversations = [
+ conversation("c1", InAppAgentRunStatus.RUNNING),
+ ];
+
+ const { rerender } = render(<ActivityProbe visibleConversationId="c1" />);
+
+ expect(storedKeys(RECEIPTS_KEY, "handled")).toEqual({
+ c1: "c1-run:SUCCEEDED",
+ });
+
+ // Refetch lands and the user starts a new conversation, so nothing masks
+ // the ledger any more: a receipt walked back here shows up as a badge.
+ activityMocks.conversations = [
+ conversation("c1", InAppAgentRunStatus.SUCCEEDED),
+ ];
+ rerender(<ActivityProbe visibleConversationId={null} />);
+
+ expect(attention()).toBe("0");
+ });
+
+ it("compacts against the list it fetched, then never again", () => {
+ seedLedgers({
+ c1: "c1-run:SUCCEEDED",
+ c2: "c2-run:SUCCEEDED",
+ evicted: "evicted-run:SUCCEEDED",
+ });
+ activityMocks.conversations = [
+ conversation("c1", InAppAgentRunStatus.SUCCEEDED),
+ conversation("c2", InAppAgentRunStatus.SUCCEEDED),
+ ];
+
+ const { rerender } = render(<ActivityProbe visibleConversationId={null} />);
+
+ // Conversations that left the activity window are storage the ledgers no
+ // longer need, so the first fetch drops them.
+ expect(storedKeys(RECEIPTS_KEY, "handled")).toEqual({
+ c1: "c1-run:SUCCEEDED",
+ c2: "c2-run:SUCCEEDED",
+ });
+ expect(storedKeys(DELIVERED_KEY, "delivered")).toEqual({
+ c1: "c1-run:SUCCEEDED",
+ c2: "c2-run:SUCCEEDED",
+ });
+
+ // The tab is backgrounded and stops polling, so its list drifts behind the
+ // ledgers it shares. Deleting is what compaction does, so it runs once.
+ activityMocks.conversations = [
+ conversation("c2", InAppAgentRunStatus.SUCCEEDED),
+ ];
+ rerender(<ActivityProbe visibleConversationId={null} />);
+
+ expect(storedKeys(RECEIPTS_KEY, "handled")).toEqual({
+ c1: "c1-run:SUCCEEDED",
+ c2: "c2-run:SUCCEEDED",
+ });
+ });
+});
diff --git a/web/src/features/in-app-agent/lib/useInAppAgentActivity.ts b/web/src/features/in-app-agent/lib/useInAppAgentActivity.ts
new file mode 100644
index 0000000000..e8e03d423b
--- /dev/null
+++ b/web/src/features/in-app-agent/lib/useInAppAgentActivity.ts
@@ -0,0 +1,232 @@
+import { useCallback, useEffect, useMemo, useRef } from "react";
+
+import useLocalStorage from "@/src/components/useLocalStorage";
+import {
+ IN_APP_AGENT_ACTIVITY_LIST_LIMIT,
+ getInAppAgentActivityReceiptsStorageKey,
+ getInAppAgentDeliveredReceiptsStorageKey,
+ hasInFlightInAppAgentActivity,
+ markInAppAgentActivityDelivered,
+ markInAppAgentConversationHandled,
+ mergeInAppAgentReceipts,
+ pruneInAppAgentDeliveredReceipts,
+ pruneInAppAgentReceipts,
+ reconcileInAppAgentActivity,
+ type InAppAgentActivityAcknowledgement,
+ type InAppAgentActivityByConversationId,
+ type InAppAgentActivityConversation,
+ type InAppAgentActivityReceipts,
+ type InAppAgentDeliveredReceipts,
+} from "@/src/features/in-app-agent/lib/inAppAgentActivity";
+import { api } from "@/src/utils/api";
+
+const ACTIVITY_POLL_INTERVAL_MS = 4_000;
+
+const EMPTY_ACKNOWLEDGEMENTS: InAppAgentActivityAcknowledgement[] = [];
+
+/**
+ * Placeholder key while session.user.id is still loading. Never written —
+ * polling and ledger sync stay disabled until a real userId arrives (and the
+ * provider remounts the hook with that id so useLocalStorage re-reads).
+ */
+const PENDING_ACTIVITY_STORAGE_KEY =
+ "langfuse-in-app-agent-activity:v1:__pending__";
+const PENDING_DELIVERED_STORAGE_KEY =
+ "langfuse-in-app-agent-delivered:v1:__pending__";
+
+export function useInAppAgentActivity(params: {
+ projectId: string;
+ userId: string | null;
+ enabled: boolean;
+ visibleConversationId: string | null;
+}) {
+ const { projectId, userId, enabled, visibleConversationId } = params;
+ const ledgerReady = Boolean(userId);
+ const pollEnabled = enabled && ledgerReady;
+
+ const [receipts, setReceipts] = useLocalStorage<InAppAgentActivityReceipts>(
+ userId
+ ? getInAppAgentActivityReceiptsStorageKey(projectId, userId)
+ : PENDING_ACTIVITY_STORAGE_KEY,
+ null,
+ );
+ const [delivered, setDelivered] =
+ useLocalStorage<InAppAgentDeliveredReceipts>(
+ userId
+ ? getInAppAgentDeliveredReceiptsStorageKey(projectId, userId)
+ : PENDING_DELIVERED_STORAGE_KEY,
+ null,
+ );
+
+ // Newest-N only; see IN_APP_AGENT_ACTIVITY_LIST_LIMIT.
+ const activityQuery = api.inAppAgent.listConversations.useQuery(
+ { projectId, limit: IN_APP_AGENT_ACTIVITY_LIST_LIMIT },
+ {
+ enabled: pollEnabled,
+ refetchInterval: (query) =>
+ hasInFlightInAppAgentActivity(query.state.data?.conversations ?? [])
+ ? ACTIVITY_POLL_INTERVAL_MS
+ : false,
+ refetchIntervalInBackground: false,
+ refetchOnWindowFocus: true,
+ },
+ );
+
+ const conversations = useMemo<InAppAgentActivityConversation[]>(
+ () =>
+ (activityQuery.data?.conversations ?? []).map((conversation) => ({
+ id: conversation.id,
+ title: conversation.title,
+ latestRun: conversation.latestRun,
+ })),
+ [activityQuery.data?.conversations],
+ );
+
+ const reconciled = useMemo(() => {
+ if (!ledgerReady || activityQuery.data === undefined) {
+ return {
+ acknowledgements: EMPTY_ACKNOWLEDGEMENTS,
+ activityByConversationId:
+ new Map() as InAppAgentActivityByConversationId,
+ attentionCount: 0,
+ };
+ }
+
+ return reconcileInAppAgentActivity({
+ receipts,
+ conversations,
+ visibleConversationId:
+ typeof document === "undefined" ||
+ document.visibilityState === "visible"
+ ? visibleConversationId
+ : null,
+ });
+ }, [
+ activityQuery.data,
+ conversations,
+ ledgerReady,
+ receipts,
+ visibleConversationId,
+ ]);
+
+ // Record read receipts while rendering when the activity snapshot changes
+ // (https://react.dev/learn/you-might-not-need-an-effect). Idempotent: once
+ // every acknowledgement is in the ledger the merge is a no-op, so React does
+ // not loop. The updater merges into the freshest state rather than into the
+ // memo's copy, which another tab may already have superseded.
+ if (ledgerReady && activityQuery.data !== undefined) {
+ if (
+ mergeInAppAgentReceipts(receipts, reconciled.acknowledgements) !==
+ receipts
+ ) {
+ setReceipts((current) =>
+ mergeInAppAgentReceipts(current, reconciled.acknowledgements),
+ );
+ }
+ }
+
+ // Compaction is storage hygiene and the only operation that deletes, so it
+ // runs once against the list this tab just fetched. A tab that has since
+ // stopped polling would otherwise delete receipts for conversations its own
+ // stale list no longer knows about.
+ const hasCompactedLedgers = useRef(false);
+ useEffect(() => {
+ if (
+ !ledgerReady ||
+ activityQuery.data === undefined ||
+ hasCompactedLedgers.current
+ ) {
+ return;
+ }
+ hasCompactedLedgers.current = true;
+
+ const liveConversationIds = new Set(
+ conversations.map((conversation) => conversation.id),
+ );
+ setReceipts((current) =>
+ pruneInAppAgentReceipts(current, liveConversationIds),
+ );
+ setDelivered((current) =>
+ pruneInAppAgentDeliveredReceipts(current, liveConversationIds),
+ );
+ }, [
+ activityQuery.data,
+ conversations,
+ ledgerReady,
+ setDelivered,
+ setReceipts,
+ ]);
+
+ const markConversationHandled = useCallback(
+ (conversationId: string, activityKey: string) => {
+ if (!ledgerReady) {
+ return;
+ }
+ setReceipts((current) =>
+ markInAppAgentConversationHandled(current, conversationId, activityKey),
+ );
+ },
+ [ledgerReady, setReceipts],
+ );
+
+ const markDelivered = useCallback(
+ (
+ entries: ReadonlyArray<{ conversationId: string; activityKey: string }>,
+ ) => {
+ if (!ledgerReady) {
+ return;
+ }
+ setDelivered((current) =>
+ markInAppAgentActivityDelivered(current, entries),
+ );
+ },
+ [ledgerReady, setDelivered],
+ );
+
+ useEffect(() => {
+ if (!visibleConversationId) {
+ return;
+ }
+
+ const handleVisibilityChange = () => {
+ if (document.visibilityState !== "visible") {
+ return;
+ }
+
+ const entry = reconciled.activityByConversationId.get(
+ visibleConversationId,
+ );
+ if (entry?.needsAttention) {
+ markConversationHandled(visibleConversationId, entry.activityKey);
+ }
+ };
+
+ document.addEventListener("visibilitychange", handleVisibilityChange);
+ return () => {
+ document.removeEventListener("visibilitychange", handleVisibilityChange);
+ };
+ }, [
+ markConversationHandled,
+ reconciled.activityByConversationId,
+ visibleConversationId,
+ ]);
+
+ return useMemo(
+ () => ({
+ activityByConversationId: reconciled.activityByConversationId,
+ attentionCount: reconciled.attentionCount,
+ delivered,
+ refetchActivity: activityQuery.refetch,
+ markConversationHandled,
+ markDelivered,
+ }),
+ [
+ activityQuery.refetch,
+ delivered,
+ markConversationHandled,
+ markDelivered,
+ reconciled.activityByConversationId,
+ reconciled.attentionCount,
+ ],
+ );
+}
diff --git a/web/src/features/in-app-agent/lib/useInAppAgentBackgroundHint.ts b/web/src/features/in-app-agent/lib/useInAppAgentBackgroundHint.ts
new file mode 100644
index 0000000000..3072b1d392
--- /dev/null
+++ b/web/src/features/in-app-agent/lib/useInAppAgentBackgroundHint.ts
@@ -0,0 +1,54 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+/** Long enough to read one sentence, short enough to not sit on the composer. */
+const HINT_VISIBLE_MS = 5_000;
+
+/**
+ * Visibility for the background-run hint. It lives as long as the wait it
+ * describes: the timeout above, or the run settling first.
+ */
+export function useInAppAgentBackgroundHint({
+ isRunActive,
+}: {
+ isRunActive: boolean;
+}) {
+ const [isVisible, setIsVisible] = useState(false);
+ const [wasRunActive, setWasRunActive] = useState(isRunActive);
+ const hideTimeoutRef = useRef<number | null>(null);
+
+ // Settling ends the wait the hint describes. A leftover timeout is harmless:
+ // hiding twice is a no-op, and `show` re-arms it.
+ if (wasRunActive !== isRunActive) {
+ setWasRunActive(isRunActive);
+
+ if (wasRunActive) {
+ setIsVisible(false);
+ }
+ }
+
+ const hide = useCallback(() => {
+ if (hideTimeoutRef.current !== null) {
+ window.clearTimeout(hideTimeoutRef.current);
+ hideTimeoutRef.current = null;
+ }
+
+ setIsVisible(false);
+ }, []);
+
+ useEffect(() => hide, [hide]);
+
+ const show = useCallback(() => {
+ setIsVisible(true);
+
+ if (hideTimeoutRef.current !== null) {
+ window.clearTimeout(hideTimeoutRef.current);
+ }
+
+ hideTimeoutRef.current = window.setTimeout(() => {
+ hideTimeoutRef.current = null;
+ setIsVisible(false);
+ }, HINT_VISIBLE_MS);
+ }, []);
+
+ return { isVisible, show, hide };
+}
diff --git a/web/src/features/in-app-agent/server/backgroundRunService.ts b/web/src/features/in-app-agent/server/backgroundRunService.ts
index 63e996533b..64d1347261 100644
--- a/web/src/features/in-app-agent/server/backgroundRunService.ts
+++ b/web/src/features/in-app-agent/server/backgroundRunService.ts
@@ -5,6 +5,7 @@ import {
BaseError,
InAppAgentRunErrorCode,
InAppAgentRunStatus,
+ InAppAgentRunStatusSchema,
LangfuseNotFoundError,
type Plan,
} from "@langfuse/shared";
@@ -36,6 +37,7 @@ import {
import {
cancelConversationRunsInTransaction,
cleanupTerminalRunMcpApiKeys,
+ classifyStaleRun,
createQueuedRun,
decideToolApproval,
reconcileConversationRuns,
@@ -149,6 +151,48 @@ export async function getBackgroundConversationSnapshot(params: {
};
}
+export type ConversationLatestRunSummary = {
+ id: string;
+ status: InAppAgentRunStatus;
+ errorCode: string | null;
+ cancelRequested: boolean;
+};
+
+/** Compact newest-run summary for list rows. Stale overlay is read-only. */
+export function serializeConversationLatestRun(
+ run:
+ | {
+ id: string;
+ status: string | null;
+ errorCode: string | null;
+ cancelRequestedAt: Date | null;
+ createdAt: Date;
+ claimedAt: Date | null;
+ heartbeatAt: Date | null;
+ finishedAt: Date | null;
+ }
+ | null
+ | undefined,
+): ConversationLatestRunSummary | null {
+ if (!run) {
+ return null;
+ }
+
+ const parsedStatus = InAppAgentRunStatusSchema.safeParse(run.status);
+ if (!parsedStatus.success) {
+ return null;
+ }
+
+ const stale = classifyStaleRun(run, Date.now());
+
+ return {
+ id: run.id,
+ status: stale ? InAppAgentRunStatus.FAILED : parsedStatus.data,
+ errorCode: stale ? stale.errorCode : run.errorCode,
+ cancelRequested: Boolean(run.cancelRequestedAt),
+ };
+}
+
export async function startBackgroundRun(params: {
prisma: PrismaClient;
projectId: string;
diff --git a/web/src/features/in-app-agent/server/router.ts b/web/src/features/in-app-agent/server/router.ts
index cd86dc43a7..b9bbc83db5 100644
--- a/web/src/features/in-app-agent/server/router.ts
+++ b/web/src/features/in-app-agent/server/router.ts
@@ -38,6 +38,7 @@ import {
decideBackgroundApproval,
deleteBackgroundConversation,
getBackgroundConversationSnapshot,
+ serializeConversationLatestRun,
startBackgroundRun,
} from "@/src/features/in-app-agent/server/backgroundRunService";
@@ -93,6 +94,10 @@ const IN_APP_AGENT_FEEDBACK_SCORE_NAME = "in_app_agent_feedback";
const IN_APP_AGENT_FEEDBACK_ENVIRONMENT = "langfuse-in-app-agent";
export const inAppAgentRouter = createTRPCRouter({
+ // Each row carries its newest run summary for the activity poll and badges.
+ // Activity clients request the newest page only (see
+ // IN_APP_AGENT_ACTIVITY_LIST_LIMIT); quieter conversations outside that
+ // window are an accepted attention gap for now.
listConversations: protectedProjectProcedure
.input(
z.object({
@@ -127,15 +132,37 @@ export const inAppAgentRouter = createTRPCRouter({
},
orderBy: [{ updatedAt: "desc" }, { id: "desc" }],
take: input.limit + 1,
+ relationLoadStrategy: "join",
+ select: {
+ id: true,
+ title: true,
+ createdAt: true,
+ updatedAt: true,
+ runs: {
+ orderBy: { createdAt: "desc" },
+ take: 1,
+ select: {
+ id: true,
+ status: true,
+ errorCode: true,
+ cancelRequestedAt: true,
+ createdAt: true,
+ claimedAt: true,
+ heartbeatAt: true,
+ finishedAt: true,
+ },
+ },
+ },
});
const page = conversations.slice(0, input.limit);
const lastConversation = page.at(-1);
return {
- conversations: page.map((conversation) =>
- serializeConversation(conversation),
- ),
+ conversations: page.map((conversation) => ({
+ ...serializeConversation(conversation),
+ latestRun: serializeConversationLatestRun(conversation.runs[0]),
+ })),
nextCursor:
conversations.length > input.limit && lastConversation
? {
diff --git a/web/src/features/posthog-analytics/usePostHogClientCapture.ts b/web/src/features/posthog-analytics/usePostHogClientCapture.ts
index b86f44468d..7988f2553c 100644
--- a/web/src/features/posthog-analytics/usePostHogClientCapture.ts
+++ b/web/src/features/posthog-analytics/usePostHogClientCapture.ts
@@ -306,6 +306,7 @@ export const events = {
"community_hours_click",
], // also used on landing page for consistency
in_app_agent: [
+ "activity_opened",
"entry_point_click",
"new_chat_started",
"new_chat_turn",