diff --git a/apps/web/components/task/plugin-task-panel.test.tsx b/apps/web/components/task/plugin-task-panel.test.tsx
index 40aa763725..d465aa9a6e 100644
--- a/apps/web/components/task/plugin-task-panel.test.tsx
+++ b/apps/web/components/task/plugin-task-panel.test.tsx
@@ -8,6 +8,11 @@ vi.mock("@/components/state-provider", () => ({
useAppStore: (selector: (state: Record
) => unknown) =>
selector({
tasks: { activeTaskId: mockActiveTaskId, activeSessionId: mockActiveSessionId },
+ taskSessions: {
+ items: {
+ session_1: { id: "session_1", is_passthrough: false, name: "Session" },
+ },
+ },
}),
}));
@@ -53,6 +58,148 @@ describe("PluginTaskPanel", () => {
);
});
+ it("passes session kind and a presentation-scoped navigation facade", () => {
+ const onOpenMessage = vi.fn(() => ({ status: "accepted" as const }));
+ function Notes(props: {
+ sessionKind: string | null;
+ conversation: { openMessage: (messageId: string) => { status: string } };
+ }) {
+ return (
+
+ );
+ }
+ pluginRegistry
+ .forPlugin("plugin-a")
+ .registerTaskPanel({ id: "notes", title: "Notes", Component: Notes, mobileEnabled: true });
+
+ render(
+ ,
+ );
+
+ screen.getByRole("button", { name: "managed" }).click();
+ expect(onOpenMessage).toHaveBeenCalledWith("message-1");
+ });
+
+ it("reports unavailable for invalid or rejected mobile navigation", () => {
+ let emptyResult = "";
+ let rejectedResult = "";
+ const onOpenMessage = vi.fn(() => ({ status: "unavailable" as const }));
+ function Notes(props: {
+ conversation: { openMessage: (messageId: string) => { status: string } };
+ }) {
+ return (
+ <>
+
+
+
+ );
+ }
+ pluginRegistry
+ .forPlugin("plugin-a")
+ .registerTaskPanel({ id: "notes", title: "Notes", Component: Notes, mobileEnabled: true });
+
+ render(
+ ,
+ );
+
+ screen.getByRole("button", { name: "empty" }).click();
+ expect(emptyResult).toBe("unavailable");
+ expect(onOpenMessage).not.toHaveBeenCalled();
+
+ screen.getByRole("button", { name: "rejected" }).click();
+ expect(rejectedResult).toBe("unavailable");
+ expect(onOpenMessage).toHaveBeenCalledWith("message-1");
+ });
+});
+describe("PluginTaskPanel session lifecycle", () => {
+ it("keeps the panel bound to a deleted active session", () => {
+ function Notes(props: { sessionId: string | null }) {
+ return {props.sessionId}
;
+ }
+ pluginRegistry
+ .forPlugin("plugin-a")
+ .registerTaskPanel({ id: "notes", title: "Notes", Component: Notes });
+
+ const view = render(
+ ,
+ );
+ expect(screen.getByTestId("notes-session").textContent).toBe("session_1");
+
+ mockActiveSessionId = null;
+ view.rerender(
+ ,
+ );
+ expect(screen.getByTestId("notes-session").textContent).toBe("session_1");
+ });
+});
+
+describe("PluginTaskPanel failure containment", () => {
+ it("fails closed when a managed visibility predicate throws", () => {
+ function Notes() {
+ return secret panel
;
+ }
+ const consoleError = vi.spyOn(console, "error").mockImplementation(() => undefined);
+ pluginRegistry.forPlugin("plugin-a").registerTaskPanel({
+ id: "notes",
+ title: "Notes",
+ Component: Notes,
+ visible: () => {
+ throw new Error("predicate failed");
+ },
+ });
+
+ render(
+ ,
+ );
+
+ expect(screen.queryByText("secret panel")).toBeNull();
+ expect(screen.getByText("This panel is no longer available.")).not.toBeNull();
+ expect(consoleError).toHaveBeenCalledWith(
+ expect.stringContaining("plugin-a:notes"),
+ expect.any(Error),
+ );
+ consoleError.mockRestore();
+ });
+
it("renders a not-available fallback when the plugin is no longer registered (AC5)", () => {
render(
{
console.error = originalConsoleError;
});
});
+describe("PluginTaskPanel lease", () => {
+ it("revokes a panel navigation lease when visibility changes", () => {
+ let visible = true;
+ let openMessage: ((messageId: string) => { status: string }) | undefined;
+ const onOpenMessage = vi.fn(() => ({ status: "accepted" as const }));
+ function Notes(props: {
+ conversation: { openMessage: (messageId: string) => { status: string } };
+ }) {
+ openMessage = props.conversation.openMessage;
+ return visible panel
;
+ }
+ pluginRegistry.forPlugin("plugin-a").registerTaskPanel({
+ id: "notes",
+ title: "Notes",
+ Component: Notes,
+ mobileEnabled: true,
+ visible: () => visible,
+ });
+
+ const view = render(
+ ,
+ );
+ const initialOpenMessage = openMessage;
+ expect(initialOpenMessage?.("message-1").status).toBe("accepted");
+ expect(onOpenMessage).toHaveBeenCalledWith("message-1");
+
+ visible = false;
+ view.rerender(
+ ,
+ );
+
+ expect(screen.getByText("This panel is no longer available.")).not.toBeNull();
+ expect(initialOpenMessage?.("message-2").status).toBe("unavailable");
+ expect(onOpenMessage).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/apps/web/components/task/plugin-task-panel.tsx b/apps/web/components/task/plugin-task-panel.tsx
index acb9f718d4..f7161f9cd7 100644
--- a/apps/web/components/task/plugin-task-panel.tsx
+++ b/apps/web/components/task/plugin-task-panel.tsx
@@ -1,10 +1,22 @@
"use client";
+import { useEffect, useMemo, useRef } from "react";
import { useTranslation } from "react-i18next";
import { useAppStore } from "@/components/state-provider";
import { PluginErrorBoundary } from "@/components/plugins/plugin-error-boundary";
+import {
+ PluginConversationScopeProvider,
+ pluginConversationApi,
+} from "@/lib/plugins/conversation-host";
+import type { PluginTaskPanelRegistration } from "@/lib/plugins/registry-registration-types";
import { pluginRegistry, usePluginRegistry } from "@/lib/plugins/registry";
-import type { PluginPresentation } from "@/lib/plugins/types";
+import type {
+ PluginOpenMessageResult,
+ PluginPresentation,
+ PluginTaskPanelContext,
+ PluginSessionKind,
+} from "@/lib/plugins/types";
+import { useDockviewStore } from "@/lib/state/dockview-store";
export interface PluginTaskPanelContainerProps {
pluginId: string;
@@ -12,6 +24,7 @@ export interface PluginTaskPanelContainerProps {
/** Full dockview/mobile panel id, e.g. `plugin::`. */
panelId: string;
presentation: PluginPresentation;
+ onOpenMessage?: (messageId: string) => PluginOpenMessageResult;
}
function PluginTaskPanelUnavailable() {
@@ -32,42 +45,120 @@ function PluginTaskPanelFailed() {
);
}
-/**
- * Resolves `{ pluginId, panelKey }` to its current `TaskPanelRegistration`
- * and renders the plugin's `Component` with `PluginTaskPanelProps`, wrapped
- * in a `PluginErrorBoundary` (AC6) so a throw inside the plugin's render
- * can't take down the surrounding dockview/mobile layout. Renders a
- * "no longer available" fallback — not a throw — when the plugin was
- * disabled/uninstalled after the panel was opened, or the layout it was
- * restored from references a panel of a plugin that is no longer installed
- * (AC5).
- */
+export function registrationIsVisible(
+ registration: PluginTaskPanelRegistration,
+ context: PluginTaskPanelContext,
+): boolean {
+ if (!registration.visible) return true;
+ try {
+ return registration.visible(context);
+ } catch (error) {
+ console.error(
+ `[plugins] visibility predicate for "${registration.pluginId}:${registration.id}" threw`,
+ error,
+ );
+ return false;
+ }
+}
+
+type RememberedSession = { taskId: string | null; sessionId: string };
+
+function useRememberedPanelSessionId(
+ taskId: string | null,
+ activeSessionId: string | null,
+): string | null {
+ const rememberedSession = useRef(null);
+ if (activeSessionId) {
+ rememberedSession.current = { taskId, sessionId: activeSessionId };
+ }
+ return (
+ activeSessionId ??
+ (rememberedSession.current?.taskId === taskId ? rememberedSession.current.sessionId : null)
+ );
+}
+
+/** Resolves and contains one plugin-contributed task panel. */
export function PluginTaskPanel({
pluginId,
panelKey,
panelId,
presentation,
+ onOpenMessage,
}: PluginTaskPanelContainerProps) {
- // Re-render when the registry changes (plugin disable/uninstall/reload) so
- // this panel picks up the fallback the instant its registration disappears.
usePluginRegistry();
+ const { t } = useTranslation();
const taskId = useAppStore((state) => state.tasks.activeTaskId);
- const sessionId = useAppStore((state) => state.tasks.activeSessionId);
+ const activeSessionId = useAppStore((state) => state.tasks.activeSessionId);
+ // Keep the deleted session identity until the host unmounts this panel.
+ const sessionId = useRememberedPanelSessionId(taskId, activeSessionId);
+ const session = useAppStore((state) =>
+ sessionId ? state.taskSessions?.items?.[sessionId] : undefined,
+ );
const registration = pluginRegistry.getTaskPanel(pluginId, panelKey);
+ const generation = pluginRegistry.getPluginLifecycle(pluginId)?.generation ?? 0;
+ let sessionKind: PluginSessionKind = null;
+ if (sessionId) {
+ sessionKind = session?.is_passthrough ? "passthrough" : "managed";
+ }
+ const context: PluginTaskPanelContext = {
+ taskId: taskId ?? "",
+ sessionId,
+ sessionKind,
+ presentation,
+ };
+ const registrationVisible = registration ? registrationIsVisible(registration, context) : false;
- if (!registration || !taskId) {
+ const lease = useMemo(
+ () => ({ active: true }),
+ [generation, panelId, panelKey, pluginId, presentation, registrationVisible, sessionId, taskId],
+ );
+ useEffect(
+ () => () => {
+ lease.active = false;
+ },
+ [lease],
+ );
+ const conversation = useMemo(
+ () => ({
+ history: pluginConversationApi,
+ openMessage(messageId: string): PluginOpenMessageResult {
+ if (!lease.active || !sessionId || messageId.trim() === "") {
+ return { status: "unavailable" };
+ }
+ if (presentation === "mobile") {
+ return onOpenMessage?.(messageId) ?? { status: "unavailable" };
+ }
+ const queued = useDockviewStore
+ .getState()
+ .scrollTranscriptToMessage(sessionId, messageId, session?.name || t("task:chat"));
+ return { status: queued ? "accepted" : "unavailable" };
+ },
+ }),
+ [lease, onOpenMessage, presentation, session?.name, sessionId, t],
+ );
+
+ if (!registration || !taskId || !registrationVisible) {
return ;
}
- const { Component } = registration;
return (
}>
-
+ >
+
+
);
}
diff --git a/apps/web/components/task/task-chat-panel.scroll-target.test.tsx b/apps/web/components/task/task-chat-panel.scroll-target.test.tsx
index 95a84b4349..249486d774 100644
--- a/apps/web/components/task/task-chat-panel.scroll-target.test.tsx
+++ b/apps/web/components/task/task-chat-panel.scroll-target.test.tsx
@@ -57,12 +57,31 @@ vi.mock("@/hooks/domains/session/load-message-window", () => ({
}));
import {
+ isMessageRowRendered,
usePendingMessageScroll,
useScrollTargetConsumption,
type PendingMessageScrollTarget,
} from "./task-chat-panel";
+import type { RenderItem } from "@/hooks/use-processed-messages";
import { loadMessageWindowAround } from "@/hooks/domains/session/load-message-window";
+describe("isMessageRowRendered", () => {
+ it("only treats direct message items as scrollable rows", () => {
+ const items = [
+ {
+ type: "turn_group",
+ id: "group-1",
+ turnId: "turn-1",
+ messages: [{ id: "grouped-prompt" }],
+ },
+ { type: "message", message: { id: "direct-prompt" } },
+ ] as unknown as RenderItem[];
+
+ expect(isMessageRowRendered(items, "grouped-prompt")).toBe(false);
+ expect(isMessageRowRendered(items, "direct-prompt")).toBe(true);
+ });
+});
+
let pendingFrames: Array<(() => void) | undefined> = [];
/** Runs two rounds of pending requestAnimationFrame callbacks inside act. */
diff --git a/apps/web/components/task/task-chat-panel.tsx b/apps/web/components/task/task-chat-panel.tsx
index ed5e930311..8fc4260c91 100644
--- a/apps/web/components/task/task-chat-panel.tsx
+++ b/apps/web/components/task/task-chat-panel.tsx
@@ -44,6 +44,8 @@ import { useLazyLoadMessages } from "@/hooks/use-lazy-load-messages";
import { findUnreadDividerItemId, lastRenderedMessageId } from "@/lib/session-unread-divider";
import { useSessionReadTracking } from "./chat/use-session-read-tracking";
import { useDrainOlderMessages } from "@/components/task/chat/use-drain-older-messages";
+import type { RenderItem } from "@/hooks/use-processed-messages";
+
import { useAppStore, useAppStoreApi } from "@/components/state-provider";
import { getSessionWorkspacePath } from "@/lib/session-workspace-path";
import type { AppState } from "@/lib/state/store";
@@ -77,6 +79,10 @@ export type PendingMessageScrollTarget = {
token: number;
hostPanelId: string;
};
+/** Reports whether a target has a dedicated DOM row in the transcript. */
+export function isMessageRowRendered(items: readonly RenderItem[], messageId: string): boolean {
+ return items.some((item) => item.type === "message" && item.message.id === messageId);
+}
/** Scrolls a non-Dockview host target after the message row becomes rendered. */
type PendingMessageScrollOptions = {
@@ -1063,8 +1069,7 @@ export const TaskChatPanel = memo(function TaskChatPanel({
messageListRef,
isInitialMessagesLoading,
targetRendered: Boolean(
- dockviewTargetMessageId &&
- allMessages.some((message) => message.id === dockviewTargetMessageId),
+ dockviewTargetMessageId && isMessageRowRendered(groupedItems, dockviewTargetMessageId),
),
renderedMessageCount: allMessages.length,
});
@@ -1229,6 +1234,7 @@ export const TaskChatPanel = memo(function TaskChatPanel({
[{value,label,color}]) so a spec can drive multi-value
+ // membership, colors, and the untagged fallback against task ids the
+ // fixture cannot know ahead of time. `window.__e2eFacetNotify()` fires
+ // the subscription so the reactive re-read path is exercised for real.
+ var facetListeners = new Set();
+
+ function emit() {
+ listeners.forEach(function (fn) {
+ fn(moduleCount);
+ });
+ }
+
+ function incrementCount() {
+ moduleCount += 1;
+ emit();
+ }
+
+ function useCounter(React) {
+ var state = React.useState(moduleCount);
+ var count = state[0];
+ var setCount = state[1];
+ React.useEffect(function () {
+ setCount(moduleCount);
+ listeners.add(setCount);
+ return function () {
+ listeners.delete(setCount);
+ };
+ }, []);
+ return count;
+ }
+
+ var PROVIDER_ID = "fixture-source-control";
+ var PULL_REQUEST_URL =
+ "https://bitbucket.example.test/projects/TEAM/repos/fixture/pull-requests/42";
+ var REPOSITORY_URL = "https://bitbucket.example.test/scm/TEAM/fixture.git";
+
+ function fixtureRepository() {
+ return {
+ id: "fixture-repository",
+ repositoryId: "fixture-repository",
+ owner: "TEAM",
+ ownerOrProject: "TEAM",
+ name: "fixture",
+ repositoryName: "fixture",
+ fullName: "TEAM/fixture",
+ url: REPOSITORY_URL,
+ cloneUrl: REPOSITORY_URL,
+ providerHost: "bitbucket.example.test",
+ defaultBranch: "main",
+ private: true,
+ };
+ }
+
+ function abortableRefresh(signal) {
+ return new Promise(function (_resolve, reject) {
+ if (signal.aborted) {
+ reject(new Error("fixture review refresh aborted"));
+ return;
+ }
+ signal.addEventListener(
+ "abort",
+ function () {
+ reject(new Error("fixture review refresh aborted"));
+ },
+ { once: true },
+ );
+ });
+ }
+
+ window.registerKandevPlugin("kandev-plugin-e2e", {
+ initialize: function (registry, host) {
+ var React = host.React;
+ var jsx = host.jsx;
+ var ui = host.ui;
+
+ // Reads host.theme once on mount, then tracks it purely through
+ // host.onThemeChange — so the readout only stays correct if the
+ // subscription actually fires. Also counts notifications, proving the
+ // host does not re-notify on unrelated class churn.
+ function useHostTheme() {
+ var state = React.useState(function () {
+ return { theme: host.theme, changes: 0 };
+ });
+ var value = state[0];
+ var setValue = state[1];
+ React.useEffect(function () {
+ return host.onThemeChange(function (next) {
+ setValue(function (prev) {
+ return { theme: next, changes: prev.changes + 1 };
+ });
+ });
+ }, []);
+ return value;
+ }
+
+ function PluginPage() {
+ var count = useCounter(React);
+ var connectionState = React.useState("Not checked");
+ var connection = connectionState[0];
+ var setConnection = connectionState[1];
+ var themeState = useHostTheme();
+ function checkConnection() {
+ host.api
+ .invokeAction("connection-status", {
+ workspaceId: host.store.getState().workspaces.activeId || undefined,
+ })
+ .then(function (result) {
+ setConnection(
+ result.connected ? "Connected" : result.error || "Connection unavailable",
+ );
+ })
+ .catch(function (error) {
+ setConnection(error instanceof Error ? error.message : "Connection unavailable");
+ });
+ }
+ return jsx(
+ "div",
+ { id: "hello-plugin-page-root" },
+ jsx("h1", { id: "hello-plugin-page" }, "Hello E2E"),
+ jsx("span", { id: "hello-task-counter" }, String(count)),
+ jsx(
+ "button",
+ {
+ id: "fixture-connection-status",
+ "data-testid": "fixture-connection-status",
+ type: "button",
+ onClick: checkConnection,
+ },
+ "Check Bitbucket connection",
+ ),
+ jsx(
+ "span",
+ { id: "fixture-connection-result", "data-testid": "fixture-connection-result" },
+ connection,
+ ),
+ jsx(
+ "span",
+ {
+ "data-testid": "hello-theme-readout",
+ "data-theme-changes": String(themeState.changes),
+ },
+ themeState.theme,
+ ),
+ // host.toast is a per-plugin Proxy over sonner; unit tests only ever
+ // see it against a mocked sonner, so this button is how an e2e
+ // proves a real toast renders and that .error does NOT file a
+ // frontend-error report.
+ jsx(
+ "button",
+ {
+ "data-testid": "hello-toast-error",
+ onClick: function () {
+ host.toast.error("Plugin toast error");
+ },
+ },
+ "toast error",
+ ),
+ );
+ }
+
+ function FixtureReviewPanel(props) {
+ return jsx(
+ "section",
+ {
+ "data-testid": "fixture-review-panel-" + props.presentation,
+ "data-review-key": props.reviewKey,
+ },
+ jsx(
+ "h2",
+ null,
+ "Bitbucket pull request #" + props.reviewKey.replace("pull-request-", ""),
+ ),
+ jsx("p", null, "Provider-neutral fixture review panel"),
+ );
+ }
+
+ function FixtureReviewSelector() {
+ return jsx("span", { "data-testid": "fixture-review-selector" }, "Bitbucket");
+ }
+
+ function openLinkResult(context) {
+ host.openTaskLinkDialog({
+ title: "Link Bitbucket pull request",
+ description: "Use a Bitbucket pull request URL for this task.",
+ inputLabel: "Pull request",
+ placeholder: PULL_REQUEST_URL,
+ emptyError: "Enter a Bitbucket pull request URL.",
+ failureMessage: "Failed to link Bitbucket pull request.",
+ successMessage: "Bitbucket pull request linked",
+ inputTestId: "fixture-link-pull-request-input",
+ errorTestId: "fixture-link-pull-request-error",
+ submitTestId: "fixture-link-pull-request-submit",
+ onSubmit: function (reference) {
+ return host.api
+ .invokeAction("link-pull-request", {
+ workspaceId: context.workspaceId,
+ taskId: context.taskId,
+ body: { pullRequestUrl: reference },
+ })
+ .then(function (result) {
+ if (!result.linked) {
+ throw new Error(result.error || "Connection unavailable");
+ }
+ });
+ },
+ });
+ return Promise.resolve();
+ }
+
+ function SidebarSlot() {
+ return jsx("div", { id: "hello-sidebar" }, "Hello E2E sidebar");
+ }
+
+ function MainTopBarSlot(props) {
+ var slotProps = props.slotProps || {};
+ var label = "Hello " + slotProps.currentPage;
+ return jsx(
+ ui.Button,
+ {
+ id: "hello-main-top-bar",
+ variant: "outline",
+ size: "icon-sm",
+ "aria-label": label,
+ },
+ jsx(
+ "svg",
+ {
+ className: "h-4 w-4",
+ viewBox: "0 0 24 24",
+ fill: "none",
+ stroke: "currentColor",
+ "aria-hidden": "true",
+ },
+ jsx("path", { d: "M5 12h14M12 5l7 7l-7 7" }),
+ ),
+ jsx("span", { className: "sr-only" }, label),
+ );
+ }
+
+ // Debounce delay for the Notes panel's autosave — short, so e2e specs
+ // don't need to wait long for a write to reach host.storage.
+ var NOTES_SAVE_DEBOUNCE_MS = 150;
+
+ function useNotesValue(taskId, panelId) {
+ var state = React.useState("");
+ var value = state[0];
+ var setValue = state[1];
+ var loadedState = React.useState(false);
+ var loaded = loadedState[0];
+ var setLoaded = loadedState[1];
+
+ React.useEffect(
+ function () {
+ var cancelled = false;
+ // Each notification (subscribe's refresh callback, plus the initial
+ // call) starts its own host.storage.get. Two in flight at once can
+ // resolve out of order, so `cancelled` alone (unmount-only) isn't
+ // enough — an older read landing after a newer one would overwrite
+ // it. Only the read matching the current generation may commit.
+ var refreshGeneration = 0;
+ function refresh() {
+ var generation = ++refreshGeneration;
+ host.storage.get("task", taskId, "note").then(
+ function (entry) {
+ if (cancelled || generation !== refreshGeneration) return;
+ setValue(entry ? entry.value : "");
+ setLoaded(true);
+ },
+ function () {
+ if (cancelled || generation !== refreshGeneration) return;
+ setLoaded(true);
+ },
+ );
+ }
+ refresh();
+ // Scope echo suppression to this panel instance (panelId) rather
+ // than the host's shared tab-wide default writerId. The kanban
+ // "Enhance notes" action below writes this same note using that
+ // shared default (it has no ongoing subscription of its own to
+ // protect) — if this panel used the same default, the action's
+ // write would look like this panel's own echo and get silently
+ // dropped instead of refreshing the panel.
+ var unsubscribe = host.storage.subscribe(
+ { scope: "task", scopeId: taskId, key: "note", writerId: panelId },
+ refresh,
+ );
+ return function () {
+ cancelled = true;
+ unsubscribe();
+ };
+ },
+ [taskId, panelId],
+ );
+
+ return [value, setValue, loaded];
+ }
+
+ function NotesPanel(props) {
+ var taskId = props.taskId;
+ var panelId = props.panelId;
+ var notesValue = useNotesValue(taskId, panelId);
+ var value = notesValue[0];
+ var setValue = notesValue[1];
+ var loaded = notesValue[2];
+ var debounceRef = React.useRef(null);
+
+ function handleChange(e) {
+ var next = e.target.value;
+ setValue(next);
+ if (debounceRef.current) clearTimeout(debounceRef.current);
+ debounceRef.current = setTimeout(function () {
+ host.storage
+ .set("task", taskId, "note", next, { writerId: panelId })
+ .catch(function () {
+ // surface the failed autosave instead of dropping it silently
+ });
+ }, NOTES_SAVE_DEBOUNCE_MS);
+ }
+
+ if (!loaded) {
+ return jsx("div", { "data-testid": "e2e-notes-panel-loading" }, "Loading notes…");
+ }
+ return jsx("textarea", {
+ "data-testid": "e2e-notes-panel",
+ "data-presentation": props.presentation,
+ value: value,
+ onChange: handleChange,
+ });
+ }
+
+ function promptDuration(startedAt, completedAt, translated) {
+ var started = Date.parse(startedAt);
+ var completed = Date.parse(completedAt);
+ if (Number.isNaN(started) || Number.isNaN(completed)) return "";
+ var seconds = Math.max(0, Math.floor((completed - started) / 1000));
+ var hours = Math.floor(seconds / 3600);
+ var minutes = Math.floor((seconds % 3600) / 60);
+ var remaining = seconds % 60;
+ if (hours > 0) {
+ return (
+ hours +
+ translated.t("durationHours") +
+ " " +
+ minutes +
+ translated.t("durationMinutes") +
+ " " +
+ remaining +
+ translated.t("durationSeconds")
+ );
+ }
+ if (minutes > 0) {
+ return (
+ minutes +
+ translated.t("durationMinutes") +
+ " " +
+ remaining +
+ translated.t("durationSeconds")
+ );
+ }
+ return remaining + translated.t("durationSeconds");
+ }
+
+ function PromptHistoryPluginRow(props) {
+ var message = props.message;
+ var turn = props.turn;
+ var translated = props.translated;
+ var duration =
+ turn && turn.completedAt
+ ? promptDuration(turn.startedAt, turn.completedAt, translated)
+ : "";
+ var favorite = props.conversation.history.useMessageFavorite(props.sessionId, message.id);
+ var isExpanded = props.expanded === message.id;
+ return jsx(
+ "article",
+ {
+ "data-testid": "fixture-prompt-history-row",
+ "data-message-id": message.id,
+ "data-favorite": favorite ? "true" : "false",
+ className: "border-b p-3",
+ },
+ jsx(
+ "button",
+ {
+ type: "button",
+ className: "min-h-11 w-full text-left",
+ onClick: function () {
+ props.setExpanded(isExpanded ? null : message.id);
+ },
+ },
+ translated.t("prompt", { values: { index: message.promptIndex || 0 } }),
+ message.senderTaskId ? " · " + translated.t("sentByAgent") : "",
+ duration
+ ? jsx("span", { "data-testid": "fixture-prompt-history-duration" }, " · " + duration)
+ : "",
+ ),
+ isExpanded
+ ? jsx(
+ "div",
+ { "data-testid": "fixture-prompt-history-detail" },
+ jsx(ui.PromptMentionText, { text: message.content, interactive: true }),
+ jsx(
+ "button",
+ {
+ type: "button",
+ className: "min-h-11",
+ onClick: function () {
+ props.conversation.openMessage(message.id);
+ },
+ },
+ translated.t("openPrompt"),
+ ),
+ )
+ : null,
+ );
+ }
+
+ function PromptHistoryPluginPanel(props) {
+ var translated = host.i18n.useTranslation();
+ var messages = props.conversation.history.useSessionMessages({
+ sessionId: props.sessionId,
+ taskId: props.taskId,
+ authorTypes: ["user"],
+ sort: "desc",
+ pageSize: 2,
+ });
+ var turns = props.conversation.history.useSessionTurns(props.sessionId, props.taskId);
+ var expandedState = React.useState(null);
+ var expanded = expandedState[0];
+ var setExpanded = expandedState[1];
+
+ if (messages.loading || turns.loading) {
+ return jsx(
+ "div",
+ { "data-testid": "fixture-prompt-history-loading" },
+ translated.t("loading"),
+ );
+ }
+ if (messages.error || turns.error) {
+ return jsx(
+ "button",
+ {
+ type: "button",
+ "data-testid": "fixture-prompt-history-error",
+ onClick: function () {
+ messages.retry();
+ turns.retry();
+ },
+ },
+ translated.t("retry"),
+ );
+ }
+ if (messages.messages.length === 0) {
+ return jsx(
+ "div",
+ { "data-testid": "fixture-prompt-history-empty" },
+ translated.t("empty"),
+ );
+ }
+ var rows = messages.messages.map(function (message) {
+ var turn = turns.turns.find(function (candidate) {
+ return candidate.id === message.turnId;
+ });
+ return jsx(PromptHistoryPluginRow, {
+ key: message.id,
+ message: message,
+ turn: turn,
+ translated: translated,
+ conversation: props.conversation,
+ sessionId: props.sessionId,
+ expanded: expanded,
+ setExpanded: setExpanded,
+ });
+ });
+ if (messages.hasMore) {
+ rows.push(
+ jsx(
+ "button",
+ {
+ key: "load-more",
+ type: "button",
+ className: "min-h-11 w-full",
+ "data-testid": "fixture-prompt-history-load-more",
+ disabled: messages.loadingMore,
+ onClick: function () {
+ messages.loadMore();
+ },
+ },
+ translated.t("loadOlder"),
+ ),
+ );
+ }
+ return jsx(
+ "div",
+ {
+ "data-testid": "fixture-prompt-history-panel",
+ "data-removed": messages.removed ? "true" : "false",
+ "data-presentation": props.presentation,
+ className: "h-full min-w-0 overflow-y-auto overflow-x-hidden",
+ },
+ rows,
+ );
+ }
+
+ function CardIndicator(props) {
+ var slotProps = props.slotProps || {};
+ return jsx(
+ "span",
+ { "data-testid": "e2e-card-indicator", "data-task-id": slotProps.taskId },
+ "N",
+ );
+ }
+
+ function CardTags(props) {
+ var slotProps = props.slotProps || {};
+ return jsx(
+ "span",
+ { "data-testid": "e2e-card-tags", "data-task-id": slotProps.taskId },
+ "tags",
+ );
+ }
+
+ function RowMetadata(props) {
+ var slotProps = props.slotProps || {};
+ return jsx(
+ "span",
+ {
+ "data-testid": "e2e-row-metadata",
+ "data-task-id": slotProps.taskId,
+ "data-surface": slotProps.surface,
+ },
+ "fixture metadata",
+ );
+ }
+
+ function WorkspaceActionsSlot(props) {
+ var slotProps = props.slotProps || {};
+ return jsx(
+ "button",
+ {
+ type: "button",
+ "data-testid": "e2e-sidebar-workspace-actions",
+ "data-workspace-id": slotProps.workspaceId,
+ "data-workspace-label": slotProps.workspaceLabel || "",
+ "data-presentation": slotProps.presentation || "unknown",
+ "aria-label": "Fixture workspace action",
+ className:
+ slotProps.presentation === "mobile"
+ ? "flex h-11 w-11 cursor-pointer items-center justify-center rounded-md border"
+ : "flex h-6 w-6 cursor-pointer items-center justify-center rounded-md border",
+ onClick: function (event) {
+ event.currentTarget.setAttribute("data-clicked", "true");
+ },
+ },
+ "W",
+ );
+ }
+
+ function StatusSlot(props) {
+ var slotProps = props.slotProps || {};
+ var id = slotProps.placement === "left" ? "hello-status-left" : "hello-status-right";
+ return jsx(
+ "span",
+ { id: id },
+ "Hello status " +
+ String(slotProps.presentation || "unknown") +
+ " " +
+ String(slotProps.activeTaskId || "no-task"),
+ );
+ }
+
+ // Drives PluginComposerCapability through native composers. Capturing
+ // the capability and using it after later renders mirrors a real voice
+ // integration whose recording completes asynchronously.
+ var COMPOSER_BUTTON_STYLE = {
+ fontSize: "9px",
+ lineHeight: "1",
+ padding: "2px 3px",
+ minWidth: "16px",
+ };
+
+ function ComposerAction(props) {
+ var slotProps = props.slotProps || {};
+ var composer = slotProps.composer;
+ var statusState = React.useState("");
+ var status = statusState[0];
+ var setStatus = statusState[1];
+ var capturedRef = React.useRef(null);
+
+ function record(result) {
+ setStatus(result && result.status ? result.status : String(result));
+ }
+
+ return jsx(
+ "span",
+ {
+ "data-testid": "e2e-composer-action",
+ "data-surface": String(slotProps.surface),
+ "data-presentation": String(slotProps.presentation),
+ "data-task-id": String(slotProps.taskId || ""),
+ "data-session-id": String(slotProps.activeSessionId || ""),
+ "data-disabled": String(Boolean(slotProps.disabled)),
+ "data-submittable": String(Boolean(slotProps.submittable)),
+ "data-status": status,
+ },
+ jsx(
+ "button",
+ {
+ type: "button",
+ "data-testid": "e2e-composer-insert",
+ style: COMPOSER_BUTTON_STYLE,
+ onClick: function () {
+ record(composer.insertText("DICTATED"));
+ },
+ },
+ "insert",
+ ),
+ jsx(
+ "button",
+ {
+ type: "button",
+ "data-testid": "e2e-composer-capture",
+ style: COMPOSER_BUTTON_STYLE,
+ onClick: function () {
+ capturedRef.current = composer;
+ setStatus("captured");
+ },
+ },
+ "capture",
+ ),
+ jsx(
+ "button",
+ {
+ type: "button",
+ "data-testid": "e2e-composer-insert-captured",
+ style: COMPOSER_BUTTON_STYLE,
+ onClick: function () {
+ record(
+ capturedRef.current
+ ? capturedRef.current.insertText("DICTATED")
+ : { status: "not-captured" },
+ );
+ },
+ },
+ "insert captured",
+ ),
+ jsx(
+ "button",
+ {
+ type: "button",
+ "data-testid": "e2e-composer-submit",
+ style: COMPOSER_BUTTON_STYLE,
+ onClick: function () {
+ var target = capturedRef.current || composer;
+ target.submit().then(record);
+ },
+ },
+ "submit",
+ ),
+ jsx(
+ "button",
+ {
+ type: "button",
+ "data-testid": "e2e-composer-focus",
+ style: COMPOSER_BUTTON_STYLE,
+ onClick: function () {
+ record(composer.focus());
+ },
+ },
+ "focus",
+ ),
+ );
+ }
+
+ function FixtureBitbucketIcon(props) {
+ return jsx(
+ "svg",
+ {
+ className: props.className,
+ viewBox: "0 0 24 24",
+ fill: "none",
+ stroke: "currentColor",
+ "aria-hidden": props["aria-hidden"] || true,
+ "data-testid": "fixture-bitbucket-icon",
+ },
+ jsx("path", { d: "M4 5h16l-2.5 14h-11z" }),
+ jsx("path", { d: "M9 9h6l-1 6h-4z" }),
+ );
+ }
+
+ registry.registerNavItem({
+ id: "e2e-hello",
+ label: "Hello E2E",
+ path: "/plugins/e2e-hello",
+ section: "main",
+ });
+ registry.registerNavItem({
+ id: "e2e-insights-tools",
+ label: "E2E Insights Tools",
+ path: "/plugins/e2e-hello",
+ section: "sidebar-footer",
+ });
+ // Three more sidebar-footer items so this one plugin install alone
+ // produces P = 4 (budget MAX_INLINE_PLUGIN_FOOTER_ITEMS = 3, plus one
+ // over-budget item) — enough to drive the desktop footer's overflow
+ // trigger and menu with the real Radix DropdownMenu in a browser (see
+ // plugins.spec.ts's overflow test). The budget counts destinations,
+ // not distinct plugins, so one plugin registering 4 items exercises
+ // the same partition as 4 plugins registering 1 each. Labeled
+ // "E2E Overflow Item N" rather than a numbered suffix of the first
+ // item's own label ("E2E Insights Tools") so Playwright's default
+ // substring name matching can't accidentally match more than one of
+ // these from an existing test written against the first item's label.
+ registry.registerNavItem({
+ id: "e2e-insights-tools-2",
+ label: "E2E Overflow Item 2",
+ path: "/plugins/e2e-hello",
+ section: "sidebar-footer",
+ });
+ registry.registerNavItem({
+ id: "e2e-insights-tools-3",
+ label: "E2E Overflow Item 3",
+ path: "/plugins/e2e-hello",
+ section: "sidebar-footer",
+ });
+ registry.registerNavItem({
+ id: "e2e-insights-tools-4",
+ label: "E2E Overflow Item 4",
+ path: "/plugins/e2e-hello",
+ section: "sidebar-footer",
+ });
+ registry.registerRoute("/plugins/e2e-hello", PluginPage);
+ registry.registerComponent("task-sidebar", SidebarSlot);
+ registry.registerComponent("main-top-bar", MainTopBarSlot);
+ registry.registerComponent("app-status-bar-left", StatusSlot);
+ registry.registerComponent("app-status-bar-right", StatusSlot);
+ registry.registerWsHandler("task.created", function () {
+ incrementCount();
+ });
+
+ registry.registerRepositoryProvider({
+ id: PROVIDER_ID,
+ label: "Bitbucket",
+ icon: FixtureBitbucketIcon,
+ listRepositories: function () {
+ return Promise.resolve([fixtureRepository()]);
+ },
+ matchesURL: function (url) {
+ if (typeof url !== "string") return false;
+ try {
+ return new URL(url).hostname === "bitbucket.example.test";
+ } catch (_error) {
+ return false;
+ }
+ },
+ listBranches: function (_context) {
+ return Promise.resolve([{ name: "main" }, { name: "feature/provider-contract" }]);
+ },
+ inspectURL: function (_context) {
+ return Promise.resolve({
+ providerId: PROVIDER_ID,
+ providerHost: "bitbucket.example.test",
+ ownerOrProject: "TEAM",
+ repositoryId: "fixture-repository",
+ repositoryName: "fixture",
+ cloneUrl: REPOSITORY_URL,
+ defaultBranch: "main",
+ baseBranch: "main",
+ headBranch: "feature/provider-contract",
+ pullRequest: { number: 42, title: "Provider-neutral contract" },
+ });
+ },
+ });
+
+ registry.registerTaskAction({
+ id: "link-bitbucket-pull-request",
+ label: "Bitbucket Pull Request",
+ icon: FixtureBitbucketIcon,
+ placement: "link",
+ group: "Link",
+ run: openLinkResult,
+ });
+
+ registry.registerReviewProvider({
+ id: PROVIDER_ID,
+ label: "Bitbucket",
+ icon: FixtureBitbucketIcon,
+ changeRequestNoun: "Pull Request",
+ order: 50,
+ getSnapshot: function (taskId) {
+ return [
+ {
+ providerId: PROVIDER_ID,
+ reviewKey: "pull-request-42",
+ title: "Bitbucket Pull Request #42",
+ url: PULL_REQUEST_URL,
+ connectionScope: "https://bitbucket.example.test",
+ repositoryId: "fixture-repository",
+ changeRequestNumber: 42,
+ state: "OPEN",
+ statusBadge: { label: "Open" },
+ taskId: taskId,
+ },
+ {
+ providerId: PROVIDER_ID,
+ reviewKey: "pull-request-43",
+ title: "Bitbucket Pull Request #43",
+ url: "https://bitbucket.example.test/projects/TEAM/repos/fixture/pull-requests/43",
+ connectionScope: "https://bitbucket.example.test",
+ repositoryId: "fixture-repository",
+ changeRequestNumber: 43,
+ state: "OPEN",
+ statusBadge: { label: "Open" },
+ taskId: taskId,
+ },
+ ];
+ },
+ subscribe: function () {
+ return function () {};
+ },
+ refresh: function (_taskId, signal) {
+ return abortableRefresh(signal);
+ },
+ ReviewPanel: FixtureReviewPanel,
+ Selector: FixtureReviewSelector,
+ });
+
+ registry.registerTranslations({
+ en: {
+ promptHistoryTitle: "Prompt history fixture",
+ loading: "Loading prompt history",
+ retry: "Retry",
+ empty: "No prompts yet",
+ prompt: "Prompt {{index}}",
+ sentByAgent: "Sent by agent",
+ openPrompt: "Open prompt",
+ loadOlder: "Load older prompts",
+ durationSeconds: "s",
+ durationMinutes: "m",
+ durationHours: "h",
+ },
+ pseudo: {
+ promptHistoryTitle: "Ƥřǿɱƥŧ ħīşŧǿřẏ ƒīẋŧŭřḗ",
+ loading: "Ŀǿȧḓīƞɠ ƥřǿɱƥŧ ħīşŧǿřẏ",
+ retry: "Řḗŧřẏ",
+ empty: "Ƞǿ ƥřǿɱƥŧş ẏḗŧ",
+ prompt: "Ƥřǿɱƥŧ {{index}}",
+ sentByAgent: "Şḗƞŧ ƀẏ ȧɠḗƞŧ",
+ openPrompt: "Ǿƥḗƞ ƥřǿɱƥŧ",
+ loadOlder: "Ŀǿȧḓ ǿŀḓḗř ƥřǿɱƥŧş",
+ durationSeconds: "ş",
+ durationMinutes: "ɱ",
+ durationHours: "ħ",
+ },
+ });
+ registry.registerTaskPanel({
+ id: "prompt-history-plugin",
+ title: "Prompt history fixture",
+ titleKey: "promptHistoryTitle",
+ icon: "history",
+ Component: PromptHistoryPluginPanel,
+ mobileEnabled: true,
+ visible: function (context) {
+ return context.sessionKind === "managed";
+ },
+ });
+
+ registry.registerTaskPanel({
+ id: "notes",
+ title: "Notes",
+ icon: "book",
+ Component: NotesPanel,
+ mobileEnabled: true,
+ });
+ registry.registerTaskListFacet({
+ id: "fixture-tags",
+ label: "Fixture tag",
+ getValues: function (context) {
+ var byTask = window.__e2eFacetValues || {};
+ if (byTask.__throwFor === context.taskId) throw new Error("fixture facet boom");
+ return byTask[context.taskId] || [];
+ },
+ subscribe: function (listener) {
+ facetListeners.add(listener);
+ window.__e2eFacetNotify = function () {
+ facetListeners.forEach(function (fn) {
+ fn();
+ });
+ };
+ return function () {
+ facetListeners.delete(listener);
+ };
+ },
+ });
+ registry.registerComponent("chat-input-actions", ComposerAction);
+ registry.registerComponent("task-create-input-actions", ComposerAction);
+ registry.registerComponent("new-session-input-actions", ComposerAction);
+ registry.registerComponent("task-card-indicators", CardIndicator);
+ registry.registerComponent("task-card-tags", CardTags);
+ registry.registerComponent("task-row-metadata", RowMetadata);
+ registry.registerComponent("sidebar-workspace-actions", WorkspaceActionsSlot);
+ registry.registerTaskMenuAction({
+ id: "enhance-notes",
+ label: "Enhance notes",
+ group: "edit",
+ run: function (context) {
+ return host.storage
+ .set("task", context.taskId, "note", "Enhanced via plugin action")
+ .then(function () {
+ // Keep the received responsive context observable to the E2E
+ // fixture without changing the plugin-facing action contract.
+ return host.storage.set(
+ "task",
+ context.taskId,
+ "menu-presentation",
+ context.presentation,
+ );
+ });
+ },
+ });
+ registry.registerTaskMenuAction({
+ id: "inspect-task-metadata",
+ label: "Inspect task metadata",
+ group: "primary",
+ run: function (context) {
+ return host.storage.set(
+ "task",
+ context.taskId,
+ "primary-menu-presentation",
+ context.presentation,
+ );
+ },
+ });
+
+ registry.registerKeybinding("open-demo", function () {
+ function DemoModalContent() {
+ var completedState = React.useState(false);
+ var completed = completedState[0];
+ var setCompleted = completedState[1];
+ var longRows = [];
+ for (var index = 0; index < 32; index += 1) {
+ longRows.push(
+ jsx(
+ "p",
+ { key: "long-modal-row-" + index },
+ "Long plugin modal content row " +
+ String(index + 1) +
+ " keeps the opaque plugin surface growing beyond the viewport.",
+ ),
+ );
+ }
+
+ // The Tooltip is the point of this modal in e2e: PluginModalHost
+ // mounts outside AppShell, so without its own TooltipProvider a
+ // Tooltip here throws on render and the error boundary swallows the
+ // whole modal. jsdom cannot open a Radix tooltip from synthetic
+ // hover, so real pointer hover is only assertable here.
+ return jsx(
+ "div",
+ {
+ id: "hello-demo-modal",
+ "data-testid": "hello-demo-modal",
+ style: { display: "grid", gap: "8px" },
+ },
+ "Hello from the plugin modal",
+ jsx(
+ ui.Tooltip,
+ null,
+ jsx(ui.TooltipTrigger, { "data-testid": "hello-modal-tooltip-trigger" }, "hover me"),
+ jsx(ui.TooltipContent, null, "Tooltip inside a plugin modal"),
+ ),
+ jsx("div", { "data-testid": "hello-long-modal-content" }, longRows),
+ jsx(
+ "button",
+ {
+ type: "button",
+ "data-testid": "hello-long-modal-final-action",
+ style: { minHeight: "44px", padding: "8px 12px" },
+ onClick: function () {
+ setCompleted(true);
+ },
+ },
+ completed ? "Plugin modal action complete" : "Complete plugin modal action",
+ ),
+ );
+ }
+ host.openModal({
+ title: "Demo Modal",
+ content: DemoModalContent,
+ size: "md",
+ });
+ });
+ },
+ });
+})();
diff --git a/apps/web/e2e/global-setup.test.ts b/apps/web/e2e/global-setup.test.ts
index 52649deca9..db5d97f5ed 100644
--- a/apps/web/e2e/global-setup.test.ts
+++ b/apps/web/e2e/global-setup.test.ts
@@ -3,7 +3,7 @@ import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import globalSetup, { assertBackendArtifactsFresh, isContainerRun } from "./global-setup";
+import { assertBackendArtifactsFresh, isContainerRun, runGlobalSetup } from "./global-setup";
let backendDir: string;
let binPath: string;
@@ -182,6 +182,20 @@ describe("assertBackendBinaryFresh", () => {
expect(() => assertBackendBinaryFresh(backendDir, [binPath], {})).not.toThrow();
});
+ it("ignores generated plugin fixture UI rebuilt after the backend binary", () => {
+ touch(
+ path.join(backendDir, "internal", "task", "service.go"),
+ new Date("2025-01-01T00:00:00Z"),
+ );
+ touch(binPath, new Date("2026-01-01T00:00:00Z"));
+ const generated = path.join(backendDir, "cmd", "plugin-fixture", "fixture-package", "ui");
+ fs.mkdirSync(generated, { recursive: true });
+ fs.writeFileSync(path.join(generated, "bundle.js"), "generated");
+ touch(path.join(generated, "bundle.js"), new Date("2026-06-01T00:00:00Z"));
+
+ expect(() => assertBackendBinaryFresh(backendDir, [binPath], {})).not.toThrow();
+ });
+
it("ignores Go coverage and compiled-test artifacts left in the source tree", () => {
// `make -C apps/backend test-coverage` writes these next to go.mod. They are
// gitignored build outputs, so a test run must not demand a backend rebuild.
@@ -345,7 +359,7 @@ describe("globalSetup", () => {
vi.stubEnv("KANDEV_E2E_SKIP_FRESHNESS", "1");
const existsSync = vi.spyOn(fs, "existsSync").mockReturnValue(true);
- (globalSetup as () => void)();
+ runGlobalSetup({ verifyPluginFixtureIdentity: false });
expect(existsSync).toHaveBeenCalledWith(customBackend);
expect(existsSync).not.toHaveBeenCalledWith(path.join(backendDirForTest(), "bin", "kandev"));
@@ -358,7 +372,9 @@ describe("globalSetup", () => {
.spyOn(fs, "existsSync")
.mockImplementation((artifactPath) => artifactPath !== customBackend);
- expect(() => (globalSetup as () => void)()).toThrow(/KANDEV_E2E_BIN file does not exist/);
+ expect(() => runGlobalSetup({ verifyPluginFixtureIdentity: false })).toThrow(
+ /KANDEV_E2E_BIN file does not exist/,
+ );
expect(existsSync).toHaveBeenCalledWith(customBackend);
});
@@ -376,7 +392,7 @@ describe("globalSetup", () => {
vi.stubEnv(marker, value);
const existsSync = vi.spyOn(fs, "existsSync").mockReturnValue(true);
- (globalSetup as () => void)();
+ runGlobalSetup({ verifyPluginFixtureIdentity: false });
expect(existsSync).toHaveBeenCalledWith(
path.join(backendDirForTest(), "bin", "mock-agent-linux-amd64"),
@@ -393,7 +409,7 @@ describe("globalSetup", () => {
process.argv = [...originalArgv, "--project=containers"];
const existsSync = vi.spyOn(fs, "existsSync").mockReturnValue(true);
- (globalSetup as () => void)();
+ runGlobalSetup({ verifyPluginFixtureIdentity: false });
expect(existsSync).toHaveBeenCalledWith(
path.join(backendDirForTest(), "bin", "mock-agent-linux-amd64"),
@@ -410,7 +426,7 @@ describe("globalSetup", () => {
process.argv = [...originalArgv, "--project=kubernetes-compat"];
const existsSync = vi.spyOn(fs, "existsSync").mockReturnValue(true);
- (globalSetup as () => void)();
+ runGlobalSetup({ verifyPluginFixtureIdentity: false });
expect(existsSync).toHaveBeenCalledWith(
path.join(backendDirForTest(), "bin", "mock-agent-linux-amd64"),
@@ -426,7 +442,7 @@ describe("globalSetup", () => {
vi.stubEnv("KANDEV_E2E_DOCKER", "");
const existsSync = vi.spyOn(fs, "existsSync").mockReturnValue(true);
- (globalSetup as () => void)();
+ runGlobalSetup({ verifyPluginFixtureIdentity: false });
expect(existsSync).not.toHaveBeenCalledWith(
path.join(backendDirForTest(), "bin", "mock-agent-linux-amd64"),
diff --git a/apps/web/e2e/global-setup.ts b/apps/web/e2e/global-setup.ts
index d45095a26c..0505a5ae99 100644
--- a/apps/web/e2e/global-setup.ts
+++ b/apps/web/e2e/global-setup.ts
@@ -10,7 +10,15 @@ export type BackendArtifact = {
rebuildTarget: string;
};
+export type GlobalSetupOptions = {
+ verifyPluginFixtureIdentity?: boolean;
+};
+
export default function globalSetup() {
+ runGlobalSetup();
+}
+
+export function runGlobalSetup(options: GlobalSetupOptions = {}): void {
const customKandevBin = process.env.KANDEV_E2E_BIN;
const kandevBin = customKandevBin ?? path.join(BACKEND_DIR, "bin", "kandev");
const artifacts: BackendArtifact[] = [
@@ -44,6 +52,11 @@ export default function globalSetup() {
assertArtifactExists(artifact.path, artifact.rebuildTarget);
}
assertBackendArtifactsFresh(BACKEND_DIR, artifacts);
+ const pluginIdentityPath = path.join(BACKEND_DIR, ".build", "e2e-plugin-identity.json");
+ assertArtifactExists(pluginIdentityPath, "e2e-plugin-package");
+ if (options.verifyPluginFixtureIdentity !== false) {
+ assertPluginFixtureIdentity(pluginIdentityPath);
+ }
const spaIndex = path.join(WEB_DIR, "dist", "index.html");
if (!fs.existsSync(spaIndex)) {
@@ -136,6 +149,7 @@ const BACKEND_SOURCE_SKIP_FILE_PATTERNS = [
* pointless backend rebuild over a bundle the tests ignore.
*/
const EMBEDDED_WEB_DIR = path.join("internal", "webapp", "embedded", "generated");
+const GENERATED_PLUGIN_FIXTURE_UI_DIR = path.join("cmd", "plugin-fixture", "fixture-package", "ui");
/**
* Every file counts, not just `*.go`: the binary `//go:embed`s a large asset
@@ -160,6 +174,7 @@ function findNewestBackendSource(
if (entry.isDirectory()) {
if (BACKEND_SOURCE_SKIP_DIRS.has(entry.name)) continue;
if (path.relative(backendDir, entryPath) === EMBEDDED_WEB_DIR) continue;
+ if (path.relative(backendDir, entryPath) === GENERATED_PLUGIN_FIXTURE_UI_DIR) continue;
walk(entryPath);
continue;
}
@@ -276,6 +291,73 @@ function validateE2EBuildIdentity(
return true;
}
+type PluginFixtureIdentity = {
+ schemaVersion: number;
+ pluginId: string;
+ pluginVersion: string;
+ bundlePath: string;
+ sourceHash: string;
+ generatedOutputHash: string;
+ manifestHash: string;
+ archiveSha256: string;
+ manifestCapability: string;
+ minKandevVersion: string;
+ panelKey: string;
+};
+
+function assertPluginFixtureIdentity(identityPath: string): void {
+ const identity = JSON.parse(fs.readFileSync(identityPath, "utf8")) as PluginFixtureIdentity;
+ if (
+ identity.schemaVersion !== 2 ||
+ identity.pluginId !== "kandev-plugin-e2e" ||
+ identity.pluginVersion !== "1.0.0" ||
+ identity.bundlePath !== "ui/bundle.js" ||
+ identity.manifestCapability !== "messages" ||
+ identity.minKandevVersion !== "0.91.1" ||
+ identity.panelKey !== "prompt-history-plugin"
+ ) {
+ throw new Error(`Unsupported E2E plugin identity schema in ${identityPath}`);
+ }
+ const source = path.join(
+ WEB_DIR,
+ "e2e",
+ "fixtures",
+ "plugins",
+ "prompt-history-plugin",
+ "bundle.js",
+ );
+ const output = path.join(
+ BACKEND_DIR,
+ "cmd",
+ "plugin-fixture",
+ "fixture-package",
+ "ui",
+ "bundle.js",
+ );
+ const manifest = path.join(
+ BACKEND_DIR,
+ "cmd",
+ "plugin-fixture",
+ "fixture-package",
+ "manifest.yaml",
+ );
+ const archive = path.join(BACKEND_DIR, ".build", "kandev-plugin-e2e-1.0.0.tar.gz");
+ for (const [file, expected] of [
+ [source, identity.sourceHash],
+ [output, identity.generatedOutputHash],
+ [manifest, identity.manifestHash],
+ [archive, identity.archiveSha256],
+ ]) {
+ assertArtifactExists(file);
+ const actual = sha256File(file);
+ if (actual !== expected) {
+ throw new Error(
+ `E2E plugin identity checksum mismatch for ${file}: got ${actual}, expected ${expected}`,
+ );
+ }
+ }
+}
+
/**
* Fail fast when the coverage oracle is asked to run against a bundle that has
* no pseudo catalog.
diff --git a/apps/web/e2e/helpers/api-client.ts b/apps/web/e2e/helpers/api-client.ts
index 1ee3c51775..af83f20727 100644
--- a/apps/web/e2e/helpers/api-client.ts
+++ b/apps/web/e2e/helpers/api-client.ts
@@ -1519,7 +1519,7 @@ export class ApiClient {
turnStartedAt?: string;
turnCompletedAt?: string;
},
- ): Promise {
+ ): Promise<{ messageId: string; turnId: string | null }> {
const body: Record = { session_id: sessionId, type: opts.type };
if (opts.content !== undefined) body.content = opts.content;
if (opts.metadata !== undefined) body.metadata = opts.metadata;
@@ -1529,7 +1529,24 @@ export class ApiClient {
if (opts.newTurn !== undefined) body.new_turn = opts.newTurn;
if (opts.turnStartedAt !== undefined) body.turn_started_at = opts.turnStartedAt;
if (opts.turnCompletedAt !== undefined) body.turn_completed_at = opts.turnCompletedAt;
- await this.request("POST", "/api/v1/_test/messages", body);
+ const result = await this.request<{ message_id: string; turn_id?: string | null }>(
+ "POST",
+ "/api/v1/_test/messages",
+ body,
+ );
+ return { messageId: result.message_id, turnId: result.turn_id ?? null };
+ }
+
+ async updateSessionMessage(messageId: string, content: string): Promise {
+ await this.request("PATCH", `/api/v1/_test/messages/${messageId}`, { content });
+ }
+
+ async deleteSessionMessage(messageId: string): Promise {
+ await this.request("DELETE", `/api/v1/_test/messages/${messageId}`);
+ }
+
+ async completeSessionTurn(turnId: string): Promise {
+ await this.request("POST", `/api/v1/_test/turns/${turnId}/complete`);
}
async seedToolCallMessages(
@@ -2599,7 +2616,7 @@ export class ApiClient {
}
async deleteSession(sessionId: string): Promise {
- await this.request("DELETE", `/api/v1/task-sessions/${sessionId}`);
+ await this.request("DELETE", `/api/v1/_test/task-sessions/${sessionId}`);
}
async getTask(taskId: string): Promise<{
diff --git a/apps/web/e2e/helpers/causal-waits.test.ts b/apps/web/e2e/helpers/causal-waits.test.ts
index f9823901c9..a075677c9a 100644
--- a/apps/web/e2e/helpers/causal-waits.test.ts
+++ b/apps/web/e2e/helpers/causal-waits.test.ts
@@ -150,6 +150,23 @@ describe("watchWs().waitForEvent", () => {
payload: { task_id: "t1", status: "cancelled" },
});
});
+ it("resolves on an ordered session event using its legacy action alias", async () => {
+ const { page, fake } = fakePage();
+ const ws = watchWs(page);
+ const socket = fake.openSocket(GATEWAY);
+ const pending = ws.waitForEvent("session.message.added", {
+ where: (payload) => payload.session_id === "session-1",
+ });
+ socket.emit("framereceived", {
+ type: "session.event",
+ event_type: "message.added",
+ payload: { session_id: "session-1", message_id: "message-1" },
+ });
+ await expect(pending).resolves.toMatchObject({
+ eventType: "message.added",
+ payload: { session_id: "session-1", message_id: "message-1" },
+ });
+ });
it("skips notifications that fail the `where` predicate", async () => {
const { page, fake } = fakePage();
diff --git a/apps/web/e2e/helpers/causal-waits.ts b/apps/web/e2e/helpers/causal-waits.ts
index 2b9cb36912..60f49310c5 100644
--- a/apps/web/e2e/helpers/causal-waits.ts
+++ b/apps/web/e2e/helpers/causal-waits.ts
@@ -124,6 +124,7 @@ export type WsFrame = {
id?: string;
type?: string;
action?: string;
+ eventType?: string;
payload: Record;
};
@@ -160,6 +161,7 @@ function decodeFrame(payload: string | Buffer | Uint8Array): WsFrame | null {
id: typeof parsed.id === "string" ? parsed.id : undefined,
type: typeof parsed.type === "string" ? parsed.type : undefined,
action: typeof parsed.action === "string" ? parsed.action : undefined,
+ eventType: typeof parsed.event_type === "string" ? parsed.event_type : undefined,
payload: body && typeof body === "object" ? (body as Record) : {},
};
} catch {
@@ -214,6 +216,12 @@ export function watchWs(page: Page): WsWatcher {
};
}
+function matchesEventAction(frame: WsFrame, action: string): boolean {
+ if (frame.action === action) return true;
+ if (frame.type !== "session.event") return false;
+ const orderedEventType = action.startsWith("session.") ? action.slice("session.".length) : action;
+ return frame.eventType === action || frame.eventType === orderedEventType;
+}
function waitForEvent(
channels: Channels,
action: string,
@@ -227,14 +235,9 @@ function waitForEvent(
reject,
);
wait.listen(channels.received, (frame) => {
- if (frame.action !== action) return;
- // Strict, not `frame.type && ...`: a frame carrying the right `action` but
- // no `type` is not a confirmed server push, and resolving on one would be
- // the exact false-positive this module exists to remove. Matches the
- // sibling guard in `waitForResponse`. Observed gateway traffic only ever
- // carries `notification` / `response` / `request`, so nothing legitimate
- // relies on the loose form.
- if (frame.type !== "notification") return;
+ if (!matchesEventAction(frame, action)) return;
+ // Strictly require a server-push frame, including ordered session events.
+ if (frame.type !== "notification" && frame.type !== "session.event") return;
if (where && !where(frame.payload)) return;
wait.dispose();
resolve(frame);
diff --git a/apps/web/e2e/helpers/plugin-fixture.ts b/apps/web/e2e/helpers/plugin-fixture.ts
index a72a470c28..9a09326015 100644
--- a/apps/web/e2e/helpers/plugin-fixture.ts
+++ b/apps/web/e2e/helpers/plugin-fixture.ts
@@ -1,5 +1,6 @@
import path from "node:path";
import { type Page, expect } from "@playwright/test";
+import type { ApiClient } from "./api-client";
export const PLUGIN_ID = "kandev-plugin-e2e";
export const PACKAGE_PATH = path.resolve(
@@ -7,6 +8,10 @@ export const PACKAGE_PATH = path.resolve(
"../../../backend/.build/kandev-plugin-e2e-1.0.0.tar.gz",
);
+export async function uninstallFixturePlugin(apiClient: ApiClient): Promise {
+ await apiClient.rawRequest("DELETE", `/api/plugins/${PLUGIN_ID}`).catch(() => undefined);
+}
+
export async function installFixturePlugin(page: Page): Promise {
await page.goto("/settings/plugins");
await page.getByTestId("install-plugin-trigger").click();
diff --git a/apps/web/e2e/helpers/session-stream-overload.ts b/apps/web/e2e/helpers/session-stream-overload.ts
index c362b2ff3a..65bea0e944 100644
--- a/apps/web/e2e/helpers/session-stream-overload.ts
+++ b/apps/web/e2e/helpers/session-stream-overload.ts
@@ -60,7 +60,10 @@ export function noisyReceivedFrames(
frame.sessionId === sessionId &&
// A subscriber present before the burst can receive its coalesced state
// as an add; a subscriber joining mid-burst observes subsequent updates.
- (frame.action === "session.message.added" || frame.action === "session.message.updated"),
+ (frame.action === "session.message.added" ||
+ frame.action === "session.message.updated" ||
+ (frame.type === "session.event" &&
+ (frame.eventType === "message.added" || frame.eventType === "message.updated"))),
);
}
diff --git a/apps/web/e2e/helpers/ws-drop.ts b/apps/web/e2e/helpers/ws-drop.ts
index 853a80c959..2aeee69ad8 100644
--- a/apps/web/e2e/helpers/ws-drop.ts
+++ b/apps/web/e2e/helpers/ws-drop.ts
@@ -16,6 +16,12 @@ type MessageAddResponseDropController = {
droppedCount: () => number;
};
+type ExpiredPluginSnapshotController = {
+ expireNextPluginSnapshot: () => void;
+ modifiedCount: () => number;
+ pluginSubscribeCount: () => number;
+};
+
export type QueueAdmissionDropController = {
dropNextQueueAddRequest: () => void;
dropNextQueueAddResponse: (count?: number) => void;
@@ -44,18 +50,34 @@ function parseJSONFrames(message: string | Buffer): Array | null {
+ const envelope = asRecord(message);
+ const payload = asRecord(envelope?.payload);
+ const isLegacy = envelope?.action === "session.message.added" && payload?.author_type === "user";
+ const isOrdered =
+ envelope?.type === "session.event" &&
+ envelope?.event_type === "message.added" &&
+ payload?.author_type === "user";
+ if (
+ (!isLegacy && !isOrdered) ||
+ typeof payload?.content !== "string" ||
+ !payload.content.includes(prompt)
+ ) {
+ return null;
+ }
+ return payload;
+}
+
function isTargetUserMessageAdded(
message: unknown,
prompt: string,
): message is { payload: { content: string } } {
+ return targetMessagePayload(message, prompt) !== null;
+}
+
+function targetAction(message: unknown): string {
const envelope = asRecord(message);
- const payload = asRecord(envelope?.payload);
- return (
- envelope?.action === "session.message.added" &&
- payload?.author_type === "user" &&
- typeof payload.content === "string" &&
- payload.content.includes(prompt)
- );
+ return envelope?.type === "session.event" ? "session.event" : "session.message.added";
}
function filterServerFrame(
@@ -77,7 +99,7 @@ function filterServerFrame(
const parsed = JSON.parse(trimmed) as unknown;
if (isTargetUserMessageAdded(parsed, prompt)) {
didDrop = true;
- dropped.push({ action: "session.message.added", content: parsed.payload.content });
+ dropped.push({ action: targetAction(parsed), content: parsed.payload.content });
continue;
}
} catch {
@@ -95,12 +117,14 @@ export async function routeMainWebSocketWithPromptDrop(page: Page): Promise();
+ const orderedRecoveryRequestIDs = new Set();
let recoveryResponses = 0;
await page.routeWebSocket(/\/ws$/, (ws) => {
const server = ws.connectToServer();
ws.onMessage((message) => {
for (const frame of parseJSONFrames(message)) {
+ const payload = asRecord(frame.payload);
if (
promptToDrop !== null &&
frame.type === "request" &&
@@ -109,6 +133,16 @@ export async function routeMainWebSocketWithPromptDrop(page: Page): Promise dropped.length,
@@ -364,3 +407,85 @@ export async function routeMainWebSocketWithQueueAdmissionDrops(
droppedResponseCount: () => state.droppedResponses.value,
};
}
+
+/**
+ * Rewrites one plugin subscription expiry in the browser transport. The
+ * signed token remains server-valid, so the panel must exercise its normal
+ * fresh rebind path instead of relying on a relaxed backend validation rule.
+ */
+export async function routeMainWebSocketWithExpiredPluginSnapshot(
+ page: Page,
+): Promise {
+ const requestIDs = new Set();
+ let armed = false;
+ let modified = 0;
+ let pluginSubscribeRequests = 0;
+
+ await page.routeWebSocket(/\/ws$/, (ws) => {
+ const server = ws.connectToServer();
+ ws.onMessage((message) => {
+ for (const frame of parseJSONFrames(message)) {
+ const payload = asRecord(frame.payload);
+ if (
+ frame.type === "request" &&
+ frame.action === "session.subscribe" &&
+ typeof frame.id === "string" &&
+ payload?.consumer_kind === "plugin"
+ ) {
+ pluginSubscribeRequests += 1;
+ if (armed) requestIDs.add(frame.id);
+ }
+ }
+ server.send(message);
+ });
+ server.onMessage((message) => {
+ if (typeof message !== "string") {
+ ws.send(message);
+ return;
+ }
+ const rewritten: string[] = [];
+ let didRewrite = false;
+ for (const part of message.split("\n")) {
+ const trimmed = part.trim();
+ if (!trimmed) {
+ rewritten.push(part);
+ continue;
+ }
+ let frame: Record | null = null;
+ try {
+ frame = asRecord(JSON.parse(trimmed));
+ } catch {
+ // Preserve non-JSON frames.
+ }
+ if (
+ armed &&
+ frame?.type === "response" &&
+ frame.action === "session.subscribe" &&
+ typeof frame.id === "string" &&
+ requestIDs.delete(frame.id)
+ ) {
+ const payload = asRecord(frame.payload);
+ if (payload?.success === true) {
+ frame.payload = { ...payload, expires_at: "2000-01-01T00:00:00Z" };
+ rewritten.push(JSON.stringify(frame));
+ armed = false;
+ modified += 1;
+ didRewrite = true;
+ continue;
+ }
+ }
+ rewritten.push(part);
+ }
+ ws.send(didRewrite ? rewritten.join("\n") : message);
+ });
+ });
+
+ return {
+ expireNextPluginSnapshot: () => {
+ requestIDs.clear();
+ armed = true;
+ },
+ modifiedCount: () => modified,
+ pluginSubscribeCount: () => pluginSubscribeRequests,
+ };
+}
diff --git a/apps/web/e2e/helpers/ws-traffic.ts b/apps/web/e2e/helpers/ws-traffic.ts
index 1d0892dd00..a8e661b81c 100644
--- a/apps/web/e2e/helpers/ws-traffic.ts
+++ b/apps/web/e2e/helpers/ws-traffic.ts
@@ -4,6 +4,7 @@ export type GatewayTrafficFrame = {
direction: "sent" | "received";
action?: string;
type?: string;
+ eventType?: string;
sessionId?: string;
taskId?: string;
bytes: number;
@@ -74,6 +75,7 @@ function frameFromPayload(
return {
direction,
action: stringField(message?.action),
+ eventType: stringField((message as Record | null)?.event_type),
type: stringField(message?.type),
sessionId:
stringField(messagePayload?.session_id) ??
diff --git a/apps/web/e2e/scripts/run-e2e.sh b/apps/web/e2e/scripts/run-e2e.sh
index ebefac5b4b..c39120b262 100755
--- a/apps/web/e2e/scripts/run-e2e.sh
+++ b/apps/web/e2e/scripts/run-e2e.sh
@@ -167,15 +167,12 @@ build_backend_host() {
make -C "$BACKEND_DIR" "${targets[@]}" >/dev/null || die "backend build failed"
}
-# Packages the plugin-fixture SDK plugin (cmd/plugin-fixture) into
-# .build/kandev-plugin-e2e-1.0.0.tar.gz for tests/plugins/plugins.spec.ts.
-# Always built on the host — like mock-agent, e2e/global-setup.ts only checks
-# this file exists (not that it's current), so it must be rebuilt any time
-# cmd/plugin-fixture changes (this runner always rebuilds it via build_fe's
-# sibling call below, unless --no-build is set).
+# Builds the external-style fixture UI from its sole source, then packages the
+# backend and UI with their immutable identity for every host/container run.
build_plugin_package() {
- log "packaging e2e fixture plugin"
- make -C "$BACKEND_DIR" e2e-plugin-package >/dev/null || die "e2e plugin package build failed"
+ log "building and packaging e2e fixture plugin"
+ make -C "$BACKEND_DIR" e2e-plugin-ui e2e-plugin-package >/dev/null \
+ || die "e2e plugin package build failed"
}
backend_runs_in() { # $1=image — does the host-built binary run there? (glibc check, ~2s)
diff --git a/apps/web/e2e/tests/plugins/conversation-recovery.spec.ts b/apps/web/e2e/tests/plugins/conversation-recovery.spec.ts
new file mode 100644
index 0000000000..24137f6c1f
--- /dev/null
+++ b/apps/web/e2e/tests/plugins/conversation-recovery.spec.ts
@@ -0,0 +1,190 @@
+import { expect, test } from "../../fixtures/test-base";
+import type { SeedData } from "../../fixtures/test-base";
+import type { ApiClient } from "../../helpers/api-client";
+import {
+ routeMainWebSocketWithExpiredPluginSnapshot,
+ routeMainWebSocketWithPromptDrop,
+} from "../../helpers/ws-drop";
+import { installFixturePlugin, PLUGIN_ID } from "../../helpers/plugin-fixture";
+import { SessionPage } from "../../pages/session-page";
+
+const PANEL_KEY = "prompt-history-plugin";
+
+async function createSeededConversation(
+ apiClient: ApiClient,
+ seedData: SeedData,
+ title: string,
+): Promise<{ taskId: string; sessionId: string }> {
+ const task = await apiClient.createTask(seedData.workspaceId, title, {
+ description: "conversation recovery fixture",
+ workflow_id: seedData.workflowId,
+ workflow_step_id: seedData.startStepId,
+ repository_ids: [seedData.repositoryId],
+ });
+ const { session_id: sessionId } = await apiClient.seedTaskSession(task.id, {
+ state: "IDLE",
+ agentProfileId: seedData.agentProfileId,
+ repositoryId: seedData.repositoryId,
+ });
+ return { taskId: task.id, sessionId };
+}
+
+async function uninstallFixturePlugin(apiClient: ApiClient): Promise {
+ await apiClient.rawRequest("DELETE", `/api/plugins/${PLUGIN_ID}`).catch(() => undefined);
+}
+
+test.describe("Conversation recovery", () => {
+ test.afterEach(async ({ apiClient }) => uninstallFixturePlugin(apiClient));
+
+ test("repairs core messages and turns after a multi-event gap on the live socket", async ({
+ testPage,
+ apiClient,
+ seedData,
+ }) => {
+ test.setTimeout(90_000);
+ const wsDrop = await routeMainWebSocketWithPromptDrop(testPage);
+ let gatewayCloseCount = 0;
+ testPage.on("websocket", (socket) => {
+ if (!socket.url().endsWith("/ws")) return;
+ socket.on("close", () => {
+ gatewayCloseCount += 1;
+ });
+ });
+
+ const { taskId, sessionId } = await createSeededConversation(
+ apiClient,
+ seedData,
+ "Core conversation recovery",
+ );
+ await testPage.goto(`/t/${taskId}`);
+ const session = new SessionPage(testPage);
+ await session.waitForLoad();
+ await session.waitForChatIdle({ timeout: 30_000 });
+
+ const skippedPrompt = "core recovery skipped prompt";
+ const replayedPrompt = "core recovery replayed prompt";
+ wsDrop.dropPrompt(skippedPrompt);
+ const skipped = await apiClient.seedSessionMessage(sessionId, {
+ type: "message",
+ content: skippedPrompt,
+ authorType: "user",
+ newTurn: true,
+ turnStartedAt: "2026-09-14T12:00:00Z",
+ turnCompletedAt: "2026-09-14T12:00:02Z",
+ });
+ const replayed = await apiClient.seedSessionMessage(sessionId, {
+ type: "message",
+ content: replayedPrompt,
+ authorType: "user",
+ newTurn: true,
+ turnStartedAt: "2026-09-14T12:01:00Z",
+ turnCompletedAt: "2026-09-14T12:01:03Z",
+ });
+
+ await expect
+ .poll(wsDrop.droppedCount, {
+ timeout: 10_000,
+ message: "expected the first durable message event to be dropped",
+ })
+ .toBeGreaterThan(0);
+ await expect
+ .poll(wsDrop.recoveryResponseCount, {
+ timeout: 15_000,
+ message: "expected core recovery snapshots after the ordered gap",
+ })
+ .toBeGreaterThan(0);
+
+ const chat = session.activeChat();
+ await expect(chat.locator(`#msg-${skipped.messageId}`)).toBeVisible({ timeout: 15_000 });
+ await expect(chat.locator(`#msg-${replayed.messageId}`)).toBeVisible({ timeout: 15_000 });
+ await expect(
+ chat.locator(`#msg-${skipped.messageId}`).getByTestId("message-turn-duration"),
+ ).toBeVisible();
+ await expect(
+ chat.locator(`#msg-${replayed.messageId}`).getByTestId("message-turn-duration"),
+ ).toBeVisible();
+
+ const laterLive = await apiClient.seedSessionMessage(sessionId, {
+ type: "message",
+ content: "core recovery later live update",
+ authorType: "user",
+ newTurn: true,
+ turnStartedAt: "2026-09-14T12:02:00Z",
+ turnCompletedAt: "2026-09-14T12:02:01Z",
+ });
+ await expect(chat.locator(`#msg-${laterLive.messageId}`)).toBeVisible({ timeout: 15_000 });
+ expect(gatewayCloseCount, "core recovery must keep the gateway socket connected").toBe(0);
+ });
+
+ test("rebinds an expired plugin continuation and keeps paging without remount", async ({
+ testPage,
+ apiClient,
+ seedData,
+ }) => {
+ test.setTimeout(90_000);
+ await installFixturePlugin(testPage);
+ const expiry = await routeMainWebSocketWithExpiredPluginSnapshot(testPage);
+ const renewalRequests: string[] = [];
+ testPage.on("request", (request) => {
+ if (request.url().includes("/conversation/continuation/renew")) {
+ renewalRequests.push(request.url());
+ }
+ });
+
+ const { taskId, sessionId } = await createSeededConversation(
+ apiClient,
+ seedData,
+ "Plugin continuation recovery",
+ );
+ for (const [index, content] of [
+ "plugin recovery oldest prompt",
+ "plugin recovery middle prompt",
+ "plugin recovery newest prompt",
+ ].entries()) {
+ await apiClient.seedSessionMessage(sessionId, {
+ type: "message",
+ content,
+ authorType: "user",
+ newTurn: true,
+ turnStartedAt: `2026-09-14T12:0${index}:00Z`,
+ turnCompletedAt: `2026-09-14T12:0${index}:01Z`,
+ });
+ }
+
+ await testPage.goto(`/t/${taskId}`);
+ const session = new SessionPage(testPage);
+ await session.waitForLoad();
+ expiry.expireNextPluginSnapshot();
+ await session.addPanelButton().click();
+ const panelMenuItem = session.addPanelPluginItem(PLUGIN_ID, PANEL_KEY);
+ await expect(panelMenuItem).toBeVisible();
+ await panelMenuItem.click();
+
+ const panel = testPage.getByTestId("fixture-prompt-history-panel");
+ await expect(panel).toBeVisible({ timeout: 15_000 });
+ await expect(panel.getByTestId("fixture-prompt-history-row")).toHaveCount(2);
+ await expect.poll(expiry.modifiedCount).toBe(1);
+
+ await panel.getByTestId("fixture-prompt-history-load-more").click();
+ await expect
+ .poll(expiry.pluginSubscribeCount, {
+ timeout: 15_000,
+ message: "expected a fresh plugin subscription after expiry",
+ })
+ .toBeGreaterThan(1);
+ await expect(panel.getByTestId("fixture-prompt-history-row")).toHaveCount(3);
+ expect(renewalRequests).toHaveLength(0);
+
+ const laterLive = await apiClient.seedSessionMessage(sessionId, {
+ type: "message",
+ content: "plugin recovery later live prompt",
+ authorType: "user",
+ newTurn: true,
+ turnStartedAt: "2026-09-14T12:03:00Z",
+ turnCompletedAt: "2026-09-14T12:03:01Z",
+ });
+ await expect(panel.locator(`[data-message-id="${laterLive.messageId}"]`)).toBeVisible({
+ timeout: 15_000,
+ });
+ });
+});
diff --git a/apps/web/e2e/tests/plugins/mobile-prompt-history-plugin.spec.ts b/apps/web/e2e/tests/plugins/mobile-prompt-history-plugin.spec.ts
new file mode 100644
index 0000000000..1b0cd5d493
--- /dev/null
+++ b/apps/web/e2e/tests/plugins/mobile-prompt-history-plugin.spec.ts
@@ -0,0 +1,87 @@
+// Routing: /t/{taskId}. The mobile- prefix selects the mobile-chrome project.
+import { expect, test } from "../../fixtures/test-base";
+import { installFixturePlugin, uninstallFixturePlugin } from "../../helpers/plugin-fixture";
+import { SessionPage } from "../../pages/session-page";
+
+const PANEL_OPTION = "mobile-plugin-panel-option-kandev-plugin-e2e-prompt-history-plugin";
+
+test.describe("Mobile prompt-history fixture", () => {
+ test.afterEach(async ({ apiClient }) => uninstallFixturePlugin(apiClient));
+
+ test("pages, previews aliases, and navigates through the Host facade", async ({
+ testPage,
+ apiClient,
+ seedData,
+ }) => {
+ test.setTimeout(90_000);
+ await installFixturePlugin(testPage);
+ await apiClient.createPrompt("daily-mobile", "Mobile saved prompt preview");
+
+ const task = await apiClient.createTask(seedData.workspaceId, "Mobile prompt history parity", {
+ description: "mobile fixture initial prompt",
+ workflow_id: seedData.workflowId,
+ workflow_step_id: seedData.startStepId,
+ repository_ids: [seedData.repositoryId],
+ });
+ const { session_id: sessionId } = await apiClient.seedTaskSession(task.id, {
+ state: "IDLE",
+ agentProfileId: seedData.agentProfileId,
+ repositoryId: seedData.repositoryId,
+ });
+ for (let index = 0; index < 3; index += 1) {
+ await apiClient.seedSessionMessage(sessionId, {
+ type: "message",
+ content: index === 2 ? "mobile latest @daily-mobile" : `mobile older ${index}`,
+ authorType: "user",
+ newTurn: true,
+ turnStartedAt: `2026-09-07T12:0${index}:00Z`,
+ turnCompletedAt: `2026-09-07T12:0${index}:01Z`,
+ });
+ }
+
+ await testPage.goto(`/t/${task.id}`);
+ const session = new SessionPage(testPage);
+ await session.waitForLoad();
+
+ const panelsButton = testPage.getByRole("button", { name: "Panels" });
+ await expect(panelsButton).toBeVisible({ timeout: 15_000 });
+ expect((await panelsButton.boundingBox())?.height).toBeGreaterThanOrEqual(44);
+ await panelsButton.tap();
+ const option = testPage.getByTestId(PANEL_OPTION);
+ await expect(option).toBeVisible({ timeout: 10_000 });
+ expect((await option.boundingBox())?.height).toBeGreaterThanOrEqual(44);
+ await option.tap();
+
+ const panel = testPage.getByTestId("fixture-prompt-history-panel");
+ if (!(await panel.isVisible())) {
+ await panelsButton.tap();
+ await option.tap();
+ }
+ await expect(panel).toBeVisible({ timeout: 10_000 });
+ await expect(panel).toHaveAttribute("data-presentation", "mobile");
+ expect(
+ await testPage.evaluate(() => document.documentElement.scrollWidth <= window.innerWidth),
+ ).toBe(true);
+
+ const loadOlder = panel.getByTestId("fixture-prompt-history-load-more");
+ await expect(loadOlder).toBeVisible();
+ expect((await loadOlder.boundingBox())?.height).toBeGreaterThanOrEqual(44);
+ await loadOlder.tap();
+ await expect(panel.getByTestId("fixture-prompt-history-row")).toHaveCount(3);
+
+ await panel.getByTestId("fixture-prompt-history-row").first().getByRole("button").first().tap();
+ const alias = panel.getByTestId("custom-prompt-mention");
+ await expect(alias).toHaveAttribute("data-prompt-name", "daily-mobile");
+ expect((await alias.boundingBox())?.height).toBeGreaterThanOrEqual(44);
+ await alias.tap();
+ await expect(testPage.getByText("Mobile saved prompt preview")).toBeVisible();
+ await testPage.keyboard.press("Escape");
+ await expect(testPage.getByText("Mobile saved prompt preview")).toBeHidden();
+
+ const openPrompt = panel.getByRole("button", { name: "Open prompt" });
+ await expect(openPrompt).toBeVisible();
+ expect((await openPrompt.boundingBox())?.height).toBeGreaterThanOrEqual(44);
+ await openPrompt.tap();
+ await expect(session.activeChat().getByText("mobile latest", { exact: false })).toBeVisible();
+ });
+});
diff --git a/apps/web/e2e/tests/plugins/prompt-history-plugin.spec.ts b/apps/web/e2e/tests/plugins/prompt-history-plugin.spec.ts
new file mode 100644
index 0000000000..afddd0bc21
--- /dev/null
+++ b/apps/web/e2e/tests/plugins/prompt-history-plugin.spec.ts
@@ -0,0 +1,136 @@
+import { expect, test } from "../../fixtures/test-base";
+import {
+ installFixturePlugin,
+ PLUGIN_ID,
+ uninstallFixturePlugin,
+} from "../../helpers/plugin-fixture";
+import { SessionPage } from "../../pages/session-page";
+
+const PANEL_KEY = "prompt-history-plugin";
+
+test.describe("Packaged prompt-history fixture", () => {
+ test.afterEach(async ({ apiClient }) => uninstallFixturePlugin(apiClient));
+
+ test("uses only Host conversation capabilities for paging, live transitions, and navigation", async ({
+ testPage,
+ apiClient,
+ seedData,
+ }) => {
+ test.setTimeout(90_000);
+ await installFixturePlugin(testPage);
+ await apiClient.createPrompt("daily", "Saved daily prompt preview");
+ const task = await apiClient.createTask(seedData.workspaceId, "Prompt history plugin parity", {
+ description: "fixture initial prompt",
+ workflow_id: seedData.workflowId,
+ workflow_step_id: seedData.startStepId,
+ repository_ids: [seedData.repositoryId],
+ });
+ const { session_id: sessionId } = await apiClient.seedTaskSession(task.id, {
+ state: "IDLE",
+ agentProfileId: seedData.agentProfileId,
+ repositoryId: seedData.repositoryId,
+ });
+ await apiClient.seedSessionMessage(sessionId, {
+ type: "message",
+ content: "fixture oldest prompt",
+ authorType: "user",
+ newTurn: true,
+ turnStartedAt: "2026-09-07T11:59:00Z",
+ turnCompletedAt: "2026-09-07T11:59:01Z",
+ });
+ const older = await apiClient.seedSessionMessage(sessionId, {
+ type: "message",
+ content: "fixture older prompt",
+ authorType: "user",
+ newTurn: true,
+ turnStartedAt: "2026-09-07T12:00:00Z",
+ turnCompletedAt: "2026-09-07T12:00:01Z",
+ });
+ const live = await apiClient.seedSessionMessage(sessionId, {
+ type: "message",
+ content: "fixture live prompt @daily",
+ authorType: "user",
+ metadata: { sender_task_id: "fixture-agent-task" },
+ newTurn: true,
+ turnStartedAt: "2026-09-07T12:01:00Z",
+ });
+
+ await testPage.goto(`/t/${task.id}`);
+ const session = new SessionPage(testPage);
+ await session.waitForLoad();
+ await session.addPanelButton().click();
+ const menuItem = session.addPanelPluginItem(PLUGIN_ID, PANEL_KEY);
+ await expect(menuItem).toHaveText(/Prompt history fixture/);
+ await menuItem.click();
+
+ const panel = testPage.getByTestId("fixture-prompt-history-panel");
+ await expect(panel).toBeVisible({ timeout: 10_000 });
+ await expect(panel.getByTestId("fixture-prompt-history-row").first()).toContainText("Prompt");
+ const loadOlder = panel.getByTestId("fixture-prompt-history-load-more");
+ await expect(loadOlder).toBeVisible();
+ await loadOlder.click();
+ await expect(panel.locator(`[data-message-id="${live.messageId}"]`)).toContainText(
+ "Sent by agent",
+ );
+ if (!live.turnId) throw new Error("live fixture message did not create a turn");
+ await apiClient.completeSessionTurn(live.turnId);
+ await expect(
+ panel
+ .locator(`[data-message-id="${live.messageId}"]`)
+ .getByTestId("fixture-prompt-history-duration"),
+ ).toBeVisible();
+ await expect(panel.getByText("Prompt 1", { exact: false }).first()).toBeVisible();
+ await apiClient.updateSessionMessage(live.messageId, "fixture updated prompt @daily");
+ await panel
+ .getByTestId("fixture-prompt-history-row")
+ .first()
+ .getByRole("button")
+ .first()
+ .click();
+ await expect(panel.getByTestId("fixture-prompt-history-detail")).toContainText(
+ "fixture updated prompt",
+ );
+ const alias = panel.getByTestId("custom-prompt-mention");
+ await expect(alias).toHaveAttribute("data-prompt-name", "daily");
+ await alias.click();
+ await expect(testPage.getByText("Saved daily prompt preview")).toBeVisible();
+ await testPage.keyboard.press("Escape");
+ await expect(testPage.getByText("Saved daily prompt preview")).toBeHidden();
+
+ await panel.getByRole("button", { name: "Open prompt" }).click();
+ await expect(session.activeChat().locator(`#msg-${live.messageId}`)).toBeAttached();
+ const chatMessage = session.activeChat().locator(`#msg-${live.messageId}`);
+ await chatMessage.hover();
+ await chatMessage.getByRole("button", { name: "Mark message as favorite" }).click();
+ await expect(panel.locator(`[data-message-id="${live.messageId}"]`)).toHaveAttribute(
+ "data-favorite",
+ "true",
+ );
+
+ await apiClient.deleteSessionMessage(older.messageId);
+ await expect(panel.locator(`[data-message-id="${older.messageId}"]`)).toHaveCount(0);
+
+ await testPage.evaluate(() => {
+ document.cookie = "kandev_locale=pseudo; path=/; max-age=31536000; SameSite=Lax";
+ });
+ await testPage.reload();
+ await session.waitForLoad();
+ await session.addPanelButton().click();
+ const pseudoMenuItem = session.addPanelPluginItem(PLUGIN_ID, PANEL_KEY);
+ await expect(pseudoMenuItem).toHaveText(/Ƥřǿɱƥŧ ħīşŧǿřẏ ƒīẋŧŭřḗ/);
+ await pseudoMenuItem.click();
+ await expect(testPage.getByTestId("fixture-prompt-history-panel")).toContainText(/Ƥřǿɱƥŧ/);
+ await testPage.evaluate(() => {
+ document.cookie = "kandev_locale=en; path=/; max-age=31536000; SameSite=Lax";
+ });
+ await testPage.reload();
+ await session.waitForLoad();
+ await session.addPanelButton().click();
+ await session.addPanelPluginItem(PLUGIN_ID, PANEL_KEY).click();
+ const finalPanel = testPage.getByTestId("fixture-prompt-history-panel");
+ await expect(finalPanel).toBeVisible({ timeout: 10_000 });
+ await apiClient.deleteSession(sessionId);
+ await expect(finalPanel).toHaveAttribute("data-removed", "true");
+ await expect(finalPanel.locator(`[data-message-id="${live.messageId}"]`)).toBeVisible();
+ });
+});
diff --git a/apps/web/hooks/domains/session/message-window-reconciliation.test.ts b/apps/web/hooks/domains/session/message-window-reconciliation.test.ts
index 19138eff6c..c5834238b7 100644
--- a/apps/web/hooks/domains/session/message-window-reconciliation.test.ts
+++ b/apps/web/hooks/domains/session/message-window-reconciliation.test.ts
@@ -68,6 +68,22 @@ describe("reconcileLatestMessageWindow", () => {
expect(result.oldestCursor).toBe("fetched-3");
});
+ it("removes stale rows from an authoritative window while retaining older pages", () => {
+ const older = message("older-1", 1);
+ const stale = message("stale-3", 3);
+ const fetched = [message("fresh-3", 3), message("fresh-4", 4)];
+
+ const result = reconcileLatestMessageWindow({
+ cachedAtRequest: [older, stale],
+ cachedAtResponse: [older, stale],
+ fetched,
+ authoritative: true,
+ });
+
+ expect(result.messages.map(({ id }) => id)).toEqual(["older-1", "fresh-3", "fresh-4"]);
+ expect(result.oldestCursor).toBe("older-1");
+ });
+
it("sorts timestamps using sub-millisecond precision before the id tie-breaker", () => {
const earlier = message("z-earlier", 0, ".000001");
const later = message("a-later", 0, ".000002");
diff --git a/apps/web/hooks/domains/session/message-window-reconciliation.ts b/apps/web/hooks/domains/session/message-window-reconciliation.ts
index eb6b7b0673..71dc3c7f9e 100644
--- a/apps/web/hooks/domains/session/message-window-reconciliation.ts
+++ b/apps/web/hooks/domains/session/message-window-reconciliation.ts
@@ -42,6 +42,10 @@ function joinMessages(base: Message[], extras: Message[]): Message[] {
return [...base, ...extras.filter((message) => !baseIds.has(message.id))].sort(compareMessages);
}
+function isPendingLocalMessage(message: Message): boolean {
+ return message.metadata?.client_queue_id !== undefined;
+}
+
/**
* Reconcile a bounded newest-page response with the session cache while
* preserving one contiguous pagination interval.
@@ -50,9 +54,17 @@ export function reconcileLatestMessageWindow(params: {
cachedAtRequest: Message[];
cachedAtResponse: Message[];
fetched: Message[];
+ authoritative?: boolean;
}): LatestMessageWindow {
- const { cachedAtRequest, cachedAtResponse, fetched } = params;
+ const { cachedAtRequest, cachedAtResponse, fetched, authoritative = false } = params;
if (fetched.length === 0) {
+ if (authoritative) {
+ const pendingLocal = cachedAtResponse.filter(isPendingLocalMessage);
+ return {
+ messages: pendingLocal,
+ oldestCursor: pendingLocal[0]?.id ?? null,
+ };
+ }
return {
messages: cachedAtResponse,
oldestCursor: cachedAtResponse[0]?.id ?? null,
@@ -64,6 +76,18 @@ export function reconcileLatestMessageWindow(params: {
const fetchedIds = new Set(orderedFetched.map((message) => message.id));
const overlapsCachedWindow = cachedAtRequest.some((message) => fetchedIds.has(message.id));
+ if (authoritative) {
+ const cachedAtRequestIds = new Set(cachedAtRequest.map((message) => message.id));
+ const retained = cachedAtResponse.filter((message) => {
+ if (fetchedIds.has(message.id)) return false;
+ if (isPendingLocalMessage(message)) return true;
+ if (compareMessages(message, fetchedBoundary) < 0) return true;
+ return !cachedAtRequestIds.has(message.id);
+ });
+ const messages = joinMessages(orderedFetched, retained);
+ return { messages, oldestCursor: messages[0]?.id ?? null };
+ }
+
if (overlapsCachedWindow) {
const messages = joinMessages(orderedFetched, cachedAtResponse);
return { messages, oldestCursor: messages[0]?.id ?? null };
diff --git a/apps/web/hooks/domains/session/use-session-message-fetch.ts b/apps/web/hooks/domains/session/use-session-message-fetch.ts
index a1849deef4..a9798a84fb 100644
--- a/apps/web/hooks/domains/session/use-session-message-fetch.ts
+++ b/apps/web/hooks/domains/session/use-session-message-fetch.ts
@@ -44,13 +44,22 @@ export function useInitialMessageLoadingState(
]);
}
-export function getHydratedMessagesForGeneration(
- hydrationRef: SessionHydrationRef | undefined,
- sessionId: string,
- readiness: Promise,
- hydrationKey: string | undefined,
- store: SessionMessageStore,
-): Message[] | undefined {
+export function getHydratedMessagesForGeneration({
+ hydrationRef,
+ sessionId,
+ readiness,
+ hydrationKey,
+ store,
+ force = false,
+}: {
+ hydrationRef: SessionHydrationRef | undefined;
+ sessionId: string;
+ readiness: Promise;
+ hydrationKey: string | undefined;
+ store: SessionMessageStore;
+ force?: boolean;
+}): Message[] | undefined {
+ if (force) return undefined;
const generation = hydrationRef?.current;
if (
!hydrationKey ||
@@ -116,6 +125,7 @@ type DoFetchMessagesParams = {
hydrationRef?: SessionHydrationRef,
hydrationKey?: string,
onRetry?: () => void,
+ options?: MessageFetchOptions,
) => Promise;
onError?: (error: unknown) => void;
isActive?: () => boolean;
@@ -123,6 +133,12 @@ type DoFetchMessagesParams = {
canFinalizeLoading?: () => boolean;
hydrationRef?: SessionHydrationRef;
hydrationKey?: string;
+ options?: MessageFetchOptions;
+};
+
+export type MessageFetchOptions = {
+ force?: boolean;
+ authoritative?: boolean;
};
export async function doFetchMessages({
@@ -140,8 +156,9 @@ export async function doFetchMessages({
canFinalizeLoading,
hydrationRef,
hydrationKey,
-}: DoFetchMessagesParams): Promise {
- if (isInactive(isActive)) return;
+ options,
+}: DoFetchMessagesParams): Promise {
+ if (isInactive(isActive)) return false;
beginSessionFetch(taskSessionId);
setIsLoading(true);
const isInitialHistoryFetch = lastFetchedSessionIdRef.current !== taskSessionId;
@@ -155,20 +172,28 @@ export async function doFetchMessages({
setIsWaitingForInitialMessages(true);
}
try {
- await fetchAndStoreMessages(taskSessionId, store, isActive, hydrationRef, hydrationKey, () =>
- setHistoryStatus("retrying"),
+ await fetchAndStoreMessages(
+ taskSessionId,
+ store,
+ isActive,
+ hydrationRef,
+ hydrationKey,
+ () => setHistoryStatus("retrying"),
+ options,
);
- if (isInactive(isActive)) return;
+ if (isInactive(isActive)) return false;
lastFetchedSessionIdRef.current = taskSessionId;
setHistoryStatus("ready");
setHistoryError(null);
setIsWaitingForInitialMessages(false);
+ return true;
} catch (error) {
- if (isInactive(isActive)) return;
+ if (isInactive(isActive)) return false;
if (onError) onError(error);
else console.error("Failed to fetch messages:", error);
setHistoryStatus("unavailable");
setHistoryError(error);
+ return false;
} finally {
const active = !isInactive(isActive);
if (endSessionFetch(taskSessionId)) {
diff --git a/apps/web/hooks/domains/session/use-session-messages.test.ts b/apps/web/hooks/domains/session/use-session-messages.test.ts
index 1a718ddc4f..51b8fb9227 100644
--- a/apps/web/hooks/domains/session/use-session-messages.test.ts
+++ b/apps/web/hooks/domains/session/use-session-messages.test.ts
@@ -10,6 +10,8 @@ const mockWebSocketClient = {
request: vi.fn(),
subscribeSession: vi.fn(),
subscribeSessionWithReady: vi.fn(),
+ registerCoreSessionRecovery: vi.fn(() => vi.fn()),
+ retryCoreSessionRecovery: vi.fn(() => undefined),
};
const mockState = {
diff --git a/apps/web/hooks/domains/session/use-session-messages.ts b/apps/web/hooks/domains/session/use-session-messages.ts
index 6b22fb4f8b..841a692642 100644
--- a/apps/web/hooks/domains/session/use-session-messages.ts
+++ b/apps/web/hooks/domains/session/use-session-messages.ts
@@ -20,6 +20,7 @@ import {
doFetchMessages,
getHydratedMessagesForGeneration,
recordHydratedGeneration,
+ type MessageFetchOptions,
type SessionHydrationRef,
} from "./use-session-message-fetch";
import { useMessageFetchState } from "./use-message-fetch-state";
@@ -35,6 +36,11 @@ const INITIAL_FETCH_LIMIT = 100;
const RUNNING_BACKFILL_INITIAL_DELAY_MS = 1200;
const RUNNING_BACKFILL_INTERVAL_MS = 5000;
const MAX_HISTORY_FETCH_ATTEMPTS = 2;
+const TERMINAL_SESSION_STATES: Partial> = {
+ WAITING_FOR_INPUT: true,
+ COMPLETED: true,
+ FAILED: true,
+};
// Monotonic guard against stale concurrent fetches. Each fetch claims an
// increasing sequence number before awaiting; a completion only merges if no
@@ -204,9 +210,10 @@ function requestSessionMessages(
sessionId: string,
readiness: Promise,
cachedAtRequest: Message[],
+ force = false,
): InFlightMessageRequest {
const existing = inFlightMessageRequests.get(sessionId);
- if (existing?.readiness === readiness && !existing.settled) return existing;
+ if (!force && existing?.readiness === readiness && !existing.settled) return existing;
const requestParams = {
session_id: sessionId,
@@ -242,13 +249,22 @@ function requestSessionMessages(
}
/** Fetch latest messages via WS and merge with any that arrived via live notifications. */
-async function fetchAndStoreMessagesAttempt(
- sessionId: string,
- store: ReturnType,
- isActive?: () => boolean,
- hydrationRef?: SessionHydrationRef,
- hydrationKey?: string,
-): Promise {
+// eslint-disable-next-line complexity -- The ordered snapshot path keeps its guards adjacent to the commit fence.
+async function fetchAndStoreMessagesAttempt({
+ sessionId,
+ store,
+ isActive,
+ hydrationRef,
+ hydrationKey,
+ options,
+}: {
+ sessionId: string;
+ store: ReturnType;
+ isActive?: () => boolean;
+ hydrationRef?: SessionHydrationRef;
+ hydrationKey?: string;
+ options?: MessageFetchOptions;
+}): Promise {
const client = getWebSocketClient();
if (!client) {
return [];
@@ -260,25 +276,32 @@ async function fetchAndStoreMessagesAttempt(
const readiness = client.getSessionSubscriptionReadiness(sessionId);
await readiness;
if (isActive && !isActive()) return [];
- const hydratedMessages = getHydratedMessagesForGeneration(
+ const hydratedMessages = getHydratedMessagesForGeneration({
hydrationRef,
sessionId,
readiness,
hydrationKey,
store,
- );
+ force: options?.force,
+ });
if (hydratedMessages !== undefined) return hydratedMessages;
// The messages fetch is the session-entry chokepoint: any path that opens a
// session's transcript must also make its turns resolvable. Start it only
// after subscription acknowledgement so the REST snapshot cannot race the
// initial WebSocket subscription registration.
- void ensureSessionTurnsLoaded(sessionId, store, { readiness });
+ if (!options?.force) void ensureSessionTurnsLoaded(sessionId, store, { readiness });
const cachedAtRequest = store.getState().messages.bySession[sessionId] ?? [];
const seq = nextFetchSeq();
// Keep the snapshot on the deduplicated request. Concurrent callers may
// observe different cache contents, but reconciliation must use the
// baseline captured by the caller that actually issued the network request.
- const request = requestSessionMessages(client, sessionId, readiness, cachedAtRequest);
+ const request = requestSessionMessages(
+ client,
+ sessionId,
+ readiness,
+ cachedAtRequest,
+ options?.force,
+ );
const response = await request.promise;
if (isActive && !isActive()) return [];
const fetched = [...(response.messages ?? [])].reverse();
@@ -287,6 +310,7 @@ async function fetchAndStoreMessagesAttempt(
cachedAtRequest: request.cachedAtRequest,
cachedAtResponse: store.getState().messages.bySession[sessionId] ?? [],
fetched,
+ authoritative: options?.authoritative,
});
// Stale-fetch guard: if a newer fetch for this session already merged while
// this one was in flight, skip the merge so the older snapshot can't drop
@@ -331,16 +355,18 @@ async function fetchAndStoreMessages(
hydrationRef?: SessionHydrationRef,
hydrationKey?: string,
onRetry?: () => void,
+ options?: MessageFetchOptions,
): Promise {
for (let attempt = 0; attempt < MAX_HISTORY_FETCH_ATTEMPTS; attempt += 1) {
try {
- return await fetchAndStoreMessagesAttempt(
+ return await fetchAndStoreMessagesAttempt({
sessionId,
store,
isActive,
hydrationRef,
hydrationKey,
- );
+ options,
+ });
} catch (error) {
const retryable =
isWebSocketRequestTimeoutError(error) &&
@@ -352,6 +378,7 @@ async function fetchAndStoreMessages(
}
return [];
}
+
/**
* When the initial fetch window contains no user/agent message rows (common
* when the latest turn produced hundreds of tool calls), the chat would render
@@ -387,9 +414,8 @@ function useTerminalStateFetch(
active = false;
};
if (!taskSessionId || connectionStatus !== "connected") return deactivate;
- if (!taskSessionState || hasAgentMessage) return deactivate;
- const terminalStates = new Set(["WAITING_FOR_INPUT", "COMPLETED", "FAILED"]);
- if (!terminalStates.has(taskSessionState)) return deactivate;
+ if (!taskSessionState) return deactivate;
+ if (!TERMINAL_SESSION_STATES[taskSessionState]) return deactivate;
const key = `${taskSessionId}:${taskSessionState}`;
if (lastFetchStateKeyRef.current === key) return deactivate;
lastFetchStateKeyRef.current = key;
@@ -896,6 +922,13 @@ function useSessionHistoryRecoveryState({
return;
}
const generation = sessionFetchGenerationRef.current;
+ const clientRecovery = getWebSocketClient()?.retryCoreSessionRecovery(retrySessionId);
+ if (clientRecovery) {
+ hydrationRef.current = null;
+ fetchState.lastFetchedSessionIdRef.current = null;
+ void clientRecovery;
+ return;
+ }
fetchState.lastFetchedSessionIdRef.current = null;
fetchState.cachedRefreshGenerationRef.current += 1;
hydrationRef.current = null;
@@ -928,6 +961,74 @@ function useSessionHistoryRecoveryState({
return { retryHistory, sessionFetchGenerationRef };
}
+function useCoreSessionRecovery({
+ taskSessionId,
+ connectionStatus,
+ store,
+ fetchRefs,
+ hydrationRef,
+ hydrationKey,
+ sessionFetchGenerationRef,
+}: {
+ taskSessionId: string | null;
+ connectionStatus: string;
+ store: ReturnType;
+ fetchRefs: ReturnType["refs"];
+ hydrationRef: SessionHydrationRef;
+ hydrationKey: string;
+ sessionFetchGenerationRef: MutableRefObject;
+}): void {
+ useEffect(() => {
+ if (!taskSessionId || connectionStatus !== "connected") return;
+ const client = getWebSocketClient();
+ if (!client) return;
+ const generation = sessionFetchGenerationRef.current;
+ let active = true;
+ const isActive = () =>
+ active &&
+ sessionFetchGenerationRef.current === generation &&
+ store.getState().taskSessions.items[taskSessionId] !== undefined;
+
+ const unregister = client.registerCoreSessionRecovery(taskSessionId, async () => {
+ if (!isActive()) return false;
+ fetchRefs.lastFetchedSessionIdRef.current = null;
+ hydrationRef.current = null;
+ const readiness = client.getSessionSubscriptionReadiness(taskSessionId);
+ const [messagesReady, turnsReady] = await Promise.all([
+ doFetchMessages({
+ taskSessionId,
+ ...fetchRefs,
+ fetchAndStoreMessages,
+ isActive,
+ canFinalizeLoading: () => isActive(),
+ hydrationRef,
+ hydrationKey,
+ options: { force: true, authoritative: true },
+ }),
+ ensureSessionTurnsLoaded(taskSessionId, store, {
+ readiness,
+ force: true,
+ replace: true,
+ }),
+ ]);
+ return isActive() && messagesReady && turnsReady;
+ });
+
+ return () => {
+ active = false;
+ unregister();
+ };
+ }, [
+ connectionStatus,
+ fetchRefs,
+ hydrationKey,
+ hydrationRef,
+ sessionFetchGenerationRef,
+ store,
+ taskSessionId,
+ ]);
+}
+
export function useSessionMessages(taskSessionId: string | null): UseSessionMessagesReturn {
const store = useAppStoreApi();
const { messages, messagesMeta, taskSessionState, activeTurnId, connectionStatus } =
@@ -962,6 +1063,15 @@ export function useSessionMessages(taskSessionId: string | null): UseSessionMess
hydrationRef,
hydrationKey,
});
+ useCoreSessionRecovery({
+ taskSessionId,
+ connectionStatus,
+ store,
+ fetchRefs,
+ hydrationRef,
+ hydrationKey,
+ sessionFetchGenerationRef,
+ });
useSessionLifecycleSubscriptions({
taskSessionId,
taskSessionState,
diff --git a/apps/web/hooks/domains/session/use-session-recovery.test.tsx b/apps/web/hooks/domains/session/use-session-recovery.test.tsx
new file mode 100644
index 0000000000..b861bb7f2e
--- /dev/null
+++ b/apps/web/hooks/domains/session/use-session-recovery.test.tsx
@@ -0,0 +1,165 @@
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { Message, Turn } from "@/lib/types/http";
+import { sessionId, taskId } from "@/lib/types/ids";
+
+const listSessionTurns = vi.fn();
+const recoveryHandlers = new Map Promise>();
+const webSocketClient = {
+ getSessionSubscriptionReadiness: vi.fn(() => Promise.resolve()),
+ request: vi.fn(),
+ subscribeSessionWithReady: vi.fn(() => ({
+ ready: Promise.resolve(),
+ unsubscribe: vi.fn(),
+ })),
+ registerCoreSessionRecovery: vi.fn((id: string, handler: () => Promise) => {
+ recoveryHandlers.set(id, handler);
+ return () => recoveryHandlers.delete(id);
+ }),
+ retryCoreSessionRecovery: vi.fn(() => undefined),
+};
+
+const staleMessage = {
+ id: "message-stale",
+ task_id: taskId("task-1"),
+ session_id: sessionId("sess-1"),
+ author_type: "agent",
+ content: "old content",
+ type: "message",
+ created_at: "2026-09-14T12:00:00Z",
+} as Message;
+const repairedMessage = { ...staleMessage, content: "repaired content" };
+const repairedTurn = {
+ id: "turn-1",
+ task_id: taskId("task-1"),
+ session_id: sessionId("sess-1"),
+ started_at: "2026-09-14T11:59:00Z",
+ completed_at: "2026-09-14T12:01:00Z",
+ created_at: "2026-09-14T11:59:00Z",
+ updated_at: "2026-09-14T12:01:00Z",
+ metadata: { model: "repaired" },
+} as Turn;
+
+const state = {
+ messages: {
+ bySession: { "sess-1": [staleMessage] as Message[] },
+ metaBySession: {
+ "sess-1": {
+ historyInitialized: true,
+ hasMore: false,
+ oldestCursor: staleMessage.id,
+ isLoading: false,
+ isLoadingMore: false,
+ },
+ },
+ },
+ taskSessions: { items: { "sess-1": { id: "sess-1", state: "IDLE" } } },
+ turns: {
+ bySession: { "sess-1": [] as Turn[] },
+ activeBySession: { "sess-1": null as string | null },
+ loadedBySession: { "sess-1": true },
+ reconcileEpochBySession: { "sess-1": 0 },
+ settledBoundaryBySession: {},
+ },
+ connection: { status: "connected" },
+ mergeMessages: vi.fn(),
+ setMessagesLoading: vi.fn(),
+ mergeTurnsSnapshot: vi.fn(),
+ addTurn: vi.fn(),
+ markTurnsLoaded: vi.fn(),
+ reconcileActiveTurnAfterHydration: vi.fn(),
+ setActiveTurn: vi.fn(),
+};
+const store = { getState: () => state };
+
+vi.mock("@/lib/api/domains/session-api", () => ({
+ listSessionTurns: (...args: unknown[]) => listSessionTurns(...args),
+}));
+
+vi.mock("@/lib/ws/connection", () => ({
+ getWebSocketClient: () => webSocketClient,
+}));
+
+vi.mock("@/components/state-provider", () => ({
+ useAppStore: (selector: (value: typeof state) => unknown) => selector(state),
+ useAppStoreApi: () => store,
+}));
+
+import { useSessionMessages } from "./use-session-messages";
+
+beforeEach(() => {
+ vi.clearAllMocks();
+ recoveryHandlers.clear();
+ state.messages.bySession["sess-1"] = [staleMessage];
+ state.messages.metaBySession["sess-1"] = {
+ historyInitialized: true,
+ hasMore: false,
+ oldestCursor: staleMessage.id,
+ isLoading: false,
+ isLoadingMore: false,
+ };
+ state.turns.bySession["sess-1"] = [];
+ state.turns.loadedBySession["sess-1"] = true;
+ state.turns.activeBySession["sess-1"] = null;
+ state.connection.status = "connected";
+ listSessionTurns.mockImplementation(() =>
+ Promise.resolve({ turns: repairedTurn.id === "turn-1" ? [repairedTurn] : [] }),
+ );
+ let messageRequest = 0;
+ webSocketClient.request.mockImplementation(() => {
+ messageRequest += 1;
+ return Promise.resolve({
+ messages: messageRequest === 1 ? [staleMessage] : [repairedMessage],
+ has_more: false,
+ });
+ });
+ state.mergeMessages.mockImplementation(
+ (sessionId: string, messages: Message[], meta?: Record) => {
+ const messagesBySession = state.messages.bySession as Record;
+ const metaBySession = state.messages.metaBySession as Record>;
+ messagesBySession[sessionId] = messages;
+ Object.assign(metaBySession[sessionId], meta);
+ },
+ );
+ state.mergeTurnsSnapshot.mockImplementation(
+ (sessionId: string, turns: Turn[], _epoch: number, options?: { replace?: boolean }) => {
+ const turnsBySession = state.turns.bySession as Record;
+ turnsBySession[sessionId] = options?.replace
+ ? turns
+ : [...turnsBySession[sessionId], ...turns];
+ (state.turns.loadedBySession as Record)[sessionId] = true;
+ },
+ );
+});
+
+afterEach(() => {
+ vi.useRealTimers();
+ vi.restoreAllMocks();
+});
+
+describe("core session recovery", () => {
+ it("rehydrates both core snapshots before resuming after invalid resume", async () => {
+ const { unmount } = renderHook(() => useSessionMessages("sess-1"));
+
+ await waitFor(() => expect(recoveryHandlers.has("sess-1")).toBe(true));
+ const recover = recoveryHandlers.get("sess-1");
+ if (!recover) throw new Error("Recovery owner was not registered");
+
+ await act(async () => {
+ await expect(recover()).resolves.toBe(true);
+ });
+
+ expect(state.messages.bySession["sess-1"]).toEqual([repairedMessage]);
+ expect(state.turns.bySession["sess-1"]).toEqual([repairedTurn]);
+ expect(state.mergeMessages).toHaveBeenCalledWith(
+ "sess-1",
+ [repairedMessage],
+ expect.objectContaining({ historyInitialized: true }),
+ );
+ expect(state.mergeTurnsSnapshot).toHaveBeenCalledWith("sess-1", [repairedTurn], 0, {
+ replace: true,
+ });
+
+ unmount();
+ });
+});
diff --git a/apps/web/hooks/domains/session/use-session-turns-hydration.test.ts b/apps/web/hooks/domains/session/use-session-turns-hydration.test.ts
index 20f09e969d..f2025d16f7 100644
--- a/apps/web/hooks/domains/session/use-session-turns-hydration.test.ts
+++ b/apps/web/hooks/domains/session/use-session-turns-hydration.test.ts
@@ -211,7 +211,7 @@ describe("ensureSessionTurnsLoaded — hydration and marker", () => {
sessionId: string,
store: unknown,
options: { readiness: Promise },
- ) => Promise
+ ) => Promise
)(SESSION_ID, store, { readiness });
expect(mockListSessionTurns).toHaveBeenCalledTimes(1);
@@ -219,6 +219,30 @@ describe("ensureSessionTurnsLoaded — hydration and marker", () => {
expect.objectContaining({ id: "turn-after-reconnect" }),
);
});
+
+ it("forces an authoritative replacement even when the current generation is loaded", async () => {
+ const store = makeStore();
+ store.getState().turns.loadedBySession[SESSION_ID] = true;
+ mockListSessionTurns.mockResolvedValue({
+ turns: [makeTurn("turn-repaired")],
+ total: 1,
+ });
+
+ await expect(
+ ensureSessionTurnsLoaded(SESSION_ID, store as never, {
+ readiness: Promise.resolve(),
+ force: true,
+ replace: true,
+ }),
+ ).resolves.toBe(true);
+
+ expect(store.mergeTurnsSnapshot).toHaveBeenCalledWith(
+ SESSION_ID,
+ [expect.objectContaining({ id: "turn-repaired" })],
+ 0,
+ { replace: true },
+ );
+ });
});
describe("ensureSessionTurnsLoaded — guards and races", () => {
@@ -311,7 +335,7 @@ describe("ensureSessionTurnsLoaded — guards and races", () => {
mockListSessionTurns.mockRejectedValue(new Error(BACKEND_DOWN));
const store = makeStore();
- await ensureSessionTurnsLoaded(SESSION_ID, store as never);
+ await expect(ensureSessionTurnsLoaded(SESSION_ID, store as never)).resolves.toBe(false);
// Bounded: no unbounded hammering of a failing endpoint.
expect(mockListSessionTurns).toHaveBeenCalledTimes(3);
diff --git a/apps/web/hooks/domains/session/use-session-turns-hydration.ts b/apps/web/hooks/domains/session/use-session-turns-hydration.ts
index 52ec062c1a..82ef98eef8 100644
--- a/apps/web/hooks/domains/session/use-session-turns-hydration.ts
+++ b/apps/web/hooks/domains/session/use-session-turns-hydration.ts
@@ -8,7 +8,7 @@ const debug = createDebugLogger("messages:fetch:turns");
// loaded marker lives in the store (`turns.loadedBySession`) because it must
// be seeded by SSR hydration too; the module maps deduplicate in-flight work
// and associate a successful load with the current subscription readiness.
-const inFlightTurnsLoad = new Map>();
+const inFlightTurnsLoad = new Map>();
const lastHydrationReadiness = new Map | undefined>();
// Transient failures (network blip, backend restart) must not leave a
@@ -81,17 +81,18 @@ async function fetchAndReconcileSessionTurns(
store: ReturnType,
sessionId: string,
hydrationEpoch: number,
+ replace: boolean,
): Promise {
try {
const { turns } = await listSessionTurns(sessionId, { cache: "no-store" });
// Re-check before merging: the session may have been removed while the
// request was in flight.
const state = store.getState();
- if (!state.taskSessions.items[sessionId]) return true;
+ if (!state.taskSessions.items[sessionId]) return false;
// Merge rows, reconcile the active marker, and record the loaded marker in
// one store transaction. This keeps a live WS update from landing between
// separate row/marker writes and avoids one Zustand notification per row.
- store.getState().mergeTurnsSnapshot(sessionId, turns, hydrationEpoch);
+ store.getState().mergeTurnsSnapshot(sessionId, turns, hydrationEpoch, { replace });
return true;
} catch (err) {
debug("turn fetch failed", { sessionId, err });
@@ -124,14 +125,16 @@ async function fetchAndReconcileSessionTurns(
export async function ensureSessionTurnsLoaded(
sessionId: string,
store: ReturnType,
- options?: { readiness?: Promise },
-): Promise {
+ options?: { readiness?: Promise; force?: boolean; replace?: boolean },
+): Promise {
const readiness = options?.readiness;
+ const force = options?.force ?? false;
+ const replace = options?.replace ?? false;
while (true) {
const state = store.getState();
if (!state.taskSessions.items[sessionId]) {
lastHydrationReadiness.delete(sessionId);
- return;
+ return false;
}
const loaded = state.turns.loadedBySession[sessionId];
// A caller without a subscription-generation token keeps the historical
@@ -139,9 +142,10 @@ export async function ensureSessionTurnsLoaded(
// WebSocket subscription, so a reconnect gets one fresh REST snapshot.
if (
loaded &&
+ !force &&
(readiness === undefined || lastHydrationReadiness.get(sessionId) === readiness)
) {
- return;
+ return true;
}
const inFlight = inFlightTurnsLoad.get(sessionId);
@@ -160,16 +164,16 @@ export async function ensureSessionTurnsLoaded(
const promise = (async () => {
try {
for (let attempt = 1; ; attempt++) {
- if (await fetchAndReconcileSessionTurns(store, sessionId, hydrationEpoch)) {
+ if (await fetchAndReconcileSessionTurns(store, sessionId, hydrationEpoch, replace)) {
if (store.getState().taskSessions.items[sessionId]) {
lastHydrationReadiness.set(sessionId, readiness);
}
- return;
+ return true;
}
debug("turn fetch attempt failed", { sessionId, attempt });
if (attempt >= TURN_HYDRATION_MAX_ATTEMPTS) {
scheduleTurnHydrationRecovery(sessionId, store);
- return;
+ return false;
}
const delay = Math.min(
TURN_HYDRATION_RETRY_BASE_MS * 2 ** (attempt - 1),
@@ -182,7 +186,6 @@ export async function ensureSessionTurnsLoaded(
}
})();
inFlightTurnsLoad.set(sessionId, promise);
- await promise;
- return;
+ return await promise;
}
}
diff --git a/apps/web/hooks/processed-message-filtering.ts b/apps/web/hooks/processed-message-filtering.ts
index fd07501a09..65c0e4af7b 100644
--- a/apps/web/hooks/processed-message-filtering.ts
+++ b/apps/web/hooks/processed-message-filtering.ts
@@ -317,7 +317,9 @@ function findActiveClarification(
messages: Message[],
scope?: PendingClarificationScope,
): Message | undefined {
- return findPendingClarification(messages, scope) ?? undefined;
+ const pending = findPendingClarification(messages, scope);
+ const metadata = pending?.metadata as ClarificationRequestMetadata | undefined;
+ return metadata?.agent_disconnected === true ? undefined : (pending ?? undefined);
}
function isClarificationVisible(
diff --git a/apps/web/hooks/use-processed-messages.ts b/apps/web/hooks/use-processed-messages.ts
index fe8d08cdc4..aa3b8d80d5 100644
--- a/apps/web/hooks/use-processed-messages.ts
+++ b/apps/web/hooks/use-processed-messages.ts
@@ -151,6 +151,7 @@ export type ProcessedMessagesOptions = {
hasOlderMessages?: boolean;
lastAgentError?: LastAgentError | null;
currentTurnId?: string | null;
+ currentTurnCompleted?: boolean;
pendingAction?: TaskPendingAction | null;
};
@@ -475,9 +476,13 @@ function usePendingClarificationState(messages: Message[], options: ProcessedMes
const scope = useMemo(
() =>
hasScopeKeys
- ? { currentTurnId: options.currentTurnId, pendingAction: options.pendingAction }
+ ? {
+ currentTurnId: options.currentTurnId,
+ currentTurnCompleted: options.currentTurnCompleted,
+ pendingAction: options.pendingAction,
+ }
: undefined,
- [hasScopeKeys, options.currentTurnId, options.pendingAction],
+ [hasScopeKeys, options.currentTurnCompleted, options.currentTurnId, options.pendingAction],
);
return {
scope,
diff --git a/apps/web/lib/plugins/conversation-event-projection.ts b/apps/web/lib/plugins/conversation-event-projection.ts
new file mode 100644
index 0000000000..2caa87e6e1
--- /dev/null
+++ b/apps/web/lib/plugins/conversation-event-projection.ts
@@ -0,0 +1,104 @@
+import type { RawSessionEvent } from "@/lib/ws/client";
+import type { PluginConversationMessage, PluginConversationTurn } from "./types";
+
+export function eventField(event: RawSessionEvent, key: string): unknown {
+ if (!event.payload || typeof event.payload !== "object" || !(key in event.payload)) {
+ return undefined;
+ }
+ return Reflect.get(event.payload, key);
+}
+
+export function eventString(event: RawSessionEvent, key: string): string | null {
+ const value = eventField(event, key);
+ return typeof value === "string" && value !== "" ? value : null;
+}
+
+function compareConversationTimestamps(left: string, right: string): number {
+ const leftMilliseconds = Date.parse(left);
+ const rightMilliseconds = Date.parse(right);
+ if (Number.isFinite(leftMilliseconds) && Number.isFinite(rightMilliseconds)) {
+ if (leftMilliseconds !== rightMilliseconds)
+ return leftMilliseconds < rightMilliseconds ? -1 : 1;
+ const leftFraction = left.match(/\.(\d+)(?:Z|[+-]\d{2}:\d{2})$/)?.[1] ?? "";
+ const rightFraction = right.match(/\.(\d+)(?:Z|[+-]\d{2}:\d{2})$/)?.[1] ?? "";
+ const leftNanoseconds = leftFraction.padEnd(9, "0").slice(0, 9);
+ const rightNanoseconds = rightFraction.padEnd(9, "0").slice(0, 9);
+ if (leftNanoseconds !== rightNanoseconds) {
+ return leftNanoseconds < rightNanoseconds ? -1 : 1;
+ }
+ return 0;
+ }
+ if (left < right) return -1;
+ if (left > right) return 1;
+ return 0;
+}
+
+function compareConversationIds(left: string, right: string): number {
+ if (left < right) return -1;
+ if (left > right) return 1;
+ return 0;
+}
+
+export function compareConversationMessages(
+ left: Pick,
+ right: Pick,
+ sort: "asc" | "desc",
+): number {
+ const created = compareConversationTimestamps(left.createdAt, right.createdAt);
+ const ordered = created === 0 ? compareConversationIds(left.id, right.id) : created;
+ return sort === "asc" ? ordered : -ordered;
+}
+
+export function eventMatchesTask(event: RawSessionEvent, taskId: string | null): boolean {
+ return taskId === null || event.task_id === taskId;
+}
+
+export function messageFromEvent(event: RawSessionEvent): PluginConversationMessage | null {
+ const id = eventString(event, "message_id");
+ const authorType = eventString(event, "author_type");
+ const contentValue = eventField(event, "content");
+ const content = typeof contentValue === "string" ? contentValue : null;
+ const createdAt = eventString(event, "created_at");
+ const explicitUpdatedAt = eventString(event, "updated_at");
+ const updatedAt = explicitUpdatedAt ?? (event.event_type === "message.added" ? createdAt : null);
+ if (
+ !id ||
+ (authorType !== "user" && authorType !== "agent") ||
+ content === null ||
+ !createdAt ||
+ !updatedAt
+ ) {
+ return null;
+ }
+ const promptIndex = eventField(event, "prompt_index");
+ return {
+ id,
+ taskId: event.task_id,
+ sessionId: event.session_id,
+ turnId: eventString(event, "turn_id") ?? undefined,
+ authorType,
+ type: eventString(event, "message_type") ?? "message",
+ content,
+ createdAt,
+ updatedAt,
+ promptIndex: typeof promptIndex === "number" ? promptIndex : undefined,
+ senderTaskId: eventString(event, "sender_task_id") ?? undefined,
+ };
+}
+
+export function turnFromEvent(event: RawSessionEvent): PluginConversationTurn | null {
+ const id = eventString(event, "turn_id") ?? eventString(event, "id");
+ const startedAt = eventString(event, "started_at");
+ const explicitUpdatedAt = eventString(event, "updated_at");
+ const updatedAt =
+ explicitUpdatedAt ?? (event.event_type === "session.turn.started" ? startedAt : null);
+ if (!id || !startedAt || !updatedAt) return null;
+ return {
+ id,
+ taskId: event.task_id,
+ sessionId: event.session_id,
+ startedAt,
+ completedAt: eventString(event, "completed_at") ?? undefined,
+ updatedAt,
+ };
+}
diff --git a/apps/web/lib/plugins/conversation-host-isolation.test.tsx b/apps/web/lib/plugins/conversation-host-isolation.test.tsx
new file mode 100644
index 0000000000..47fe0df77c
--- /dev/null
+++ b/apps/web/lib/plugins/conversation-host-isolation.test.tsx
@@ -0,0 +1,592 @@
+import { act, cleanup, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { RawSessionEvent } from "@/lib/ws/client";
+import type { PluginSessionMessagesState } from "./types";
+import { PluginConversationScopeProvider, pluginConversationApi } from "./conversation-host";
+
+const transport = vi.hoisted(() => ({
+ request: vi.fn(),
+ listener: null as ((event: RawSessionEvent) => void) | null,
+}));
+
+vi.mock("@/lib/config", () => ({ getBackendConfig: () => ({ apiBaseUrl: "http://host" }) }));
+vi.mock("@/lib/ws/connection", () => ({
+ getWebSocketClient: () => ({
+ request: transport.request,
+ onRawSessionEvent(listener: (event: RawSessionEvent) => void) {
+ transport.listener = listener;
+ return () => {
+ if (transport.listener === listener) transport.listener = null;
+ };
+ },
+ onConnectionStatus(_listener: (status: "connected" | "disconnected") => void) {
+ return () => undefined;
+ },
+ }),
+}));
+const BINDING_PATH_SUFFIX = "/conversation/binding";
+const FAR_FUTURE = "2099-01-01T00:00:00Z";
+const SNAPSHOT_CREATED_AT = "2026-09-07T12:00:00Z";
+
+function ScopedHarness({ sessionId, testId }: { sessionId: string; testId: string }) {
+ const state = pluginConversationApi.useSessionMessages({ sessionId });
+ return {String(state.hydrated)};
+}
+
+let userQueryState: PluginSessionMessagesState | null = null;
+let agentQueryState: PluginSessionMessagesState | null = null;
+let ascendingState: PluginSessionMessagesState | null = null;
+
+function AscendingHarness() {
+ ascendingState = pluginConversationApi.useSessionMessages({
+ sessionId: "session-1",
+ authorTypes: ["agent"],
+ sort: "asc",
+ pageSize: 1,
+ });
+ return (
+
+ {ascendingState.messages.map((item) => item.content).join("|")}
+
+ );
+}
+
+function TwoQueryHarness() {
+ userQueryState = pluginConversationApi.useSessionMessages({
+ sessionId: "session-1",
+ authorTypes: ["user"],
+ sort: "desc",
+ pageSize: 1,
+ });
+ agentQueryState = pluginConversationApi.useSessionMessages({
+ sessionId: "session-1",
+ authorTypes: ["agent"],
+ sort: "asc",
+ pageSize: 2,
+ });
+ return (
+ <>
+
+ {userQueryState.messages.map((message) => message.content).join("|")}
+
+
+ {agentQueryState.messages.map((message) => message.content).join("|")}
+
+
+ );
+}
+
+function deferred() {
+ let resolve!: (value: T) => void;
+ const promise = new Promise((resolvePromise) => {
+ resolve = resolvePromise;
+ });
+ return { promise, resolve };
+}
+
+function message(id: string, content: string, createdAt: string, authorType: "user" | "agent") {
+ return {
+ id,
+ taskId: "task-1",
+ sessionId: "session-1",
+ authorType,
+ type: "message",
+ content,
+ createdAt,
+ updatedAt: createdAt,
+ };
+}
+
+function liveAgentEvent(sequence: number): RawSessionEvent {
+ return {
+ type: "session.event",
+ protocol_version: 1,
+ event_type: "message.added",
+ session_id: "session-1",
+ task_id: "task-1",
+ sequence,
+ event_id: `event-${sequence}`,
+ payload: {
+ type: "message.added",
+ session_id: "session-1",
+ task_id: "task-1",
+ message_id: "message-live",
+ author_type: "agent",
+ content: "live",
+ message_type: "message",
+ created_at: "2026-09-07T12:02:00Z",
+ },
+ };
+}
+
+function liveMessageDeletedEvent(sequence: number, messageId: string): RawSessionEvent {
+ return {
+ type: "session.event",
+ protocol_version: 1,
+ event_type: "message.deleted",
+ session_id: "session-1",
+ task_id: "task-1",
+ sequence,
+ event_id: `event-${sequence}`,
+ payload: {
+ type: "message.deleted",
+ session_id: "session-1",
+ task_id: "task-1",
+ message_id: messageId,
+ },
+ };
+}
+
+function response(body: unknown): Response {
+ return new Response(JSON.stringify(body), {
+ status: 200,
+ headers: { "Content-Type": "application/json" },
+ });
+}
+
+function renderScope(taskId: string, sessionId: string, testId: string) {
+ return (
+
+
+
+ );
+}
+
+function resetHarness() {
+ transport.request.mockReset();
+ transport.listener = null;
+ userQueryState = null;
+ agentQueryState = null;
+ ascendingState = null;
+ transport.request.mockResolvedValue({
+ success: true,
+ snapshot_token: "snapshot-1",
+ resume_token: "resume-1",
+ consumer_id: "consumer-1",
+ event_watermark: 0,
+ expires_at: FAR_FUTURE,
+ result: "fresh",
+ });
+ vi.stubGlobal(
+ "fetch",
+ vi.fn((input: RequestInfo | URL) => {
+ if (String(input).endsWith(BINDING_PATH_SUFFIX)) {
+ return Promise.resolve(
+ response({
+ bindingToken: "binding-1",
+ generation: 7,
+ expiresAt: FAR_FUTURE,
+ }),
+ );
+ }
+ return Promise.resolve(response({ messages: [], hasMore: false, cursor: null }));
+ }),
+ );
+}
+
+function registerIsolationLifecycle() {
+ beforeEach(resetHarness);
+ afterEach(() => {
+ cleanup();
+ vi.unstubAllGlobals();
+ });
+}
+
+describe("plugin conversation panel isolation", () => {
+ registerIsolationLifecycle();
+
+ it("gives concurrent panels independent consumer identities and snapshots", async () => {
+ render(
+ <>
+ {renderScope("task-1", "session-1", "panel-one")}
+ {renderScope("task-2", "session-2", "panel-two")}
+ ,
+ );
+
+ await waitFor(() => expect(screen.getByTestId("panel-one").textContent).toBe("true"));
+ await waitFor(() => expect(screen.getByTestId("panel-two").textContent).toBe("true"));
+ const subscriptions = transport.request.mock.calls.filter(
+ ([action]) => action === "session.subscribe",
+ );
+ expect(subscriptions).toHaveLength(2);
+ expect(subscriptions[0][1].consumer_id).not.toBe(subscriptions[1][1].consumer_id);
+ const fetchMock = vi.mocked(fetch);
+ expect(fetchMock.mock.calls.some(([input]) => String(input).includes("session-1"))).toBe(true);
+ expect(fetchMock.mock.calls.some(([input]) => String(input).includes("session-2"))).toBe(true);
+ });
+});
+
+describe("message query snapshot isolation", () => {
+ registerIsolationLifecycle();
+
+ it("buffers live events until every distinct message query commits its snapshot", async () => {
+ const userPage = deferred();
+ const agentPage = deferred();
+ vi.stubGlobal(
+ "fetch",
+ vi.fn((input: RequestInfo | URL) => {
+ const url = String(input);
+ if (url.endsWith(BINDING_PATH_SUFFIX)) {
+ return Promise.resolve(
+ response({
+ bindingToken: "binding-1",
+ generation: 7,
+ expiresAt: FAR_FUTURE,
+ }),
+ );
+ }
+ return url.includes("author_type=user") ? userPage.promise : agentPage.promise;
+ }),
+ );
+ render(
+
+
+ ,
+ );
+ await waitFor(() => expect(vi.mocked(fetch)).toHaveBeenCalledTimes(3));
+
+ await act(async () => {
+ userPage.resolve(
+ response({
+ messages: [message("message-user", "user snapshot", SNAPSHOT_CREATED_AT, "user")],
+ hasMore: false,
+ cursor: null,
+ }),
+ );
+ await userPage.promise;
+ });
+ act(() => transport.listener?.(liveAgentEvent(1)));
+
+ expect(screen.getByTestId("agent-query").textContent).toBe("");
+ expect(transport.request.mock.calls.filter(([action]) => action === "session.ack")).toEqual([]);
+
+ await act(async () => {
+ agentPage.resolve(
+ response({
+ messages: [message("message-agent", "agent snapshot", "2026-09-07T12:01:00Z", "agent")],
+ hasMore: false,
+ cursor: null,
+ }),
+ );
+ await agentPage.promise;
+ });
+ expect(screen.getByTestId("agent-query").textContent).toBe("agent snapshot|live");
+ await waitFor(() =>
+ expect(transport.request.mock.calls.some(([action]) => action === "session.ack")).toBe(true),
+ );
+ });
+});
+
+// eslint-disable-next-line max-lines-per-function -- This describe block keeps concurrent query recovery fixtures together.
+describe("message continuation isolation", () => {
+ registerIsolationLifecycle();
+
+ // eslint-disable-next-line max-lines-per-function -- This scenario covers concurrent queries across the complete expiry rebind.
+ it("renews concurrent continuations independently for distinct message queries", async () => {
+ transport.request.mockImplementation((action: string) =>
+ Promise.resolve(
+ action === "session.subscribe"
+ ? {
+ success: true,
+ snapshot_token: "snapshot-expiring",
+ resume_token: "resume-1",
+ consumer_id: "consumer-1",
+ event_watermark: 0,
+ expires_at: new Date(Date.now() + 30_000).toISOString(),
+ result: "fresh",
+ }
+ : { success: true },
+ ),
+ );
+ const renewalCursors: string[] = [];
+ const requestedPageCursors: string[] = [];
+ vi.stubGlobal(
+ "fetch",
+ vi.fn((input: RequestInfo | URL, init?: RequestInit) => {
+ const url = String(input);
+ if (url.endsWith(BINDING_PATH_SUFFIX)) {
+ return Promise.resolve(
+ response({
+ bindingToken: "binding-1",
+ generation: 7,
+ expiresAt: FAR_FUTURE,
+ }),
+ );
+ }
+ if (url.endsWith("/conversation/continuation/renew")) {
+ const body = JSON.parse(String(init?.body)) as { cursor: string };
+ renewalCursors.push(body.cursor);
+ return Promise.resolve(
+ response({
+ cursor: `renewed-${body.cursor}`,
+ snapshot_token: `snapshot-${body.cursor}`,
+ expires_at: FAR_FUTURE,
+ }),
+ );
+ }
+ const parsed = new URL(url);
+ const author = parsed.searchParams.get("author_type");
+ const cursor = parsed.searchParams.get("cursor");
+ if (cursor) requestedPageCursors.push(cursor);
+ return Promise.resolve(
+ response({
+ messages: cursor
+ ? []
+ : [
+ message(
+ `message-${author}`,
+ `${author} snapshot`,
+ SNAPSHOT_CREATED_AT,
+ author === "agent" ? "agent" : "user",
+ ),
+ ],
+ hasMore: !cursor,
+ cursor: cursor ? null : `cursor-${author}`,
+ }),
+ );
+ }),
+ );
+ render(
+
+
+ ,
+ );
+ await waitFor(() => {
+ expect(userQueryState?.hasMore).toBe(true);
+ expect(agentQueryState?.hasMore).toBe(true);
+ });
+
+ await act(async () => {
+ await Promise.all([userQueryState!.loadMore(), agentQueryState!.loadMore()]);
+ });
+
+ expect(renewalCursors.sort()).toEqual(["cursor-agent", "cursor-user"]);
+ expect(requestedPageCursors.sort()).toEqual(["renewed-cursor-agent", "renewed-cursor-user"]);
+ });
+
+ it("joins expiry recovery while preserving each query's continuation", async () => {
+ let subscribeCount = 0;
+ transport.request.mockImplementation((action: string) => {
+ if (action === "session.subscribe") {
+ subscribeCount += 1;
+ return Promise.resolve({
+ success: true,
+ snapshot_token: `snapshot-${subscribeCount}`,
+ resume_token: `resume-${subscribeCount}`,
+ consumer_id: `consumer-${subscribeCount}`,
+ event_watermark: 0,
+ expires_at: subscribeCount === 1 ? "2020-01-01T00:00:00Z" : FAR_FUTURE,
+ result: "fresh",
+ });
+ }
+ return Promise.resolve({ success: true });
+ });
+ const pageCount = new Map();
+ const continuationCursors: string[] = [];
+ const fetchMock = vi.fn((input: RequestInfo | URL) => {
+ const url = String(input);
+ if (url.endsWith(BINDING_PATH_SUFFIX)) {
+ return Promise.resolve(
+ response({ bindingToken: "binding-1", generation: 7, expiresAt: FAR_FUTURE }),
+ );
+ }
+ const parsed = new URL(url);
+ const author = parsed.searchParams.get("author_type") ?? "none";
+ const cursor = parsed.searchParams.get("cursor");
+ if (cursor) continuationCursors.push(cursor);
+ const count = (pageCount.get(author) ?? 0) + 1;
+ pageCount.set(author, count);
+ if (cursor) {
+ return Promise.resolve(
+ response({
+ messages: [
+ message(
+ `older-${author}`,
+ `${author} older`,
+ SNAPSHOT_CREATED_AT,
+ author === "agent" ? "agent" : "user",
+ ),
+ ],
+ hasMore: false,
+ cursor: null,
+ }),
+ );
+ }
+ return Promise.resolve(
+ response({
+ messages: [
+ message(
+ `current-${author}`,
+ `${author} current ${count}`,
+ SNAPSHOT_CREATED_AT,
+ author === "agent" ? "agent" : "user",
+ ),
+ ],
+ hasMore: true,
+ cursor: `${author}-cursor-${count === 1 ? "expired" : "fresh"}`,
+ }),
+ );
+ });
+ vi.stubGlobal("fetch", fetchMock);
+ render(
+
+
+ ,
+ );
+ await waitFor(() => {
+ expect(userQueryState?.hasMore).toBe(true);
+ expect(agentQueryState?.hasMore).toBe(true);
+ });
+
+ await act(async () => {
+ await Promise.all([userQueryState!.loadMore(), agentQueryState!.loadMore()]);
+ });
+
+ expect(subscribeCount).toBe(2);
+ expect(continuationCursors.sort()).toEqual(["agent-cursor-fresh", "user-cursor-fresh"]);
+ expect(screen.getByTestId("user-query").textContent).toContain("user older");
+ expect(screen.getByTestId("agent-query").textContent).toContain("agent older");
+ expect(
+ fetchMock.mock.calls.some(([input]) => String(input).includes("continuation/renew")),
+ ).toBe(false);
+ });
+});
+
+describe("ascending message pagination", () => {
+ registerIsolationLifecycle();
+
+ it("deduplicates and re-sorts an ascending list after live delivery then loadMore", async () => {
+ let messagePage = 0;
+ vi.stubGlobal(
+ "fetch",
+ vi.fn((input: RequestInfo | URL) => {
+ const url = String(input);
+ if (url.endsWith(BINDING_PATH_SUFFIX)) {
+ return Promise.resolve(
+ response({
+ bindingToken: "binding-1",
+ generation: 7,
+ expiresAt: FAR_FUTURE,
+ }),
+ );
+ }
+ messagePage += 1;
+ return Promise.resolve(
+ response(
+ messagePage === 1
+ ? {
+ messages: [message("message-base", "base", SNAPSHOT_CREATED_AT, "agent")],
+ hasMore: true,
+ cursor: "cursor-1",
+ }
+ : {
+ messages: [
+ message("message-live", "stale page", "2026-09-07T12:02:00Z", "agent"),
+ message("message-middle", "middle", "2026-09-07T12:01:00Z", "agent"),
+ ],
+ hasMore: false,
+ cursor: null,
+ },
+ ),
+ );
+ }),
+ );
+ render(
+
+
+ ,
+ );
+ await waitFor(() => expect(ascendingState?.hasMore).toBe(true));
+ act(() => transport.listener?.(liveAgentEvent(1)));
+ expect(screen.getByTestId("ascending-query").textContent).toBe("base|live");
+
+ await act(async () => {
+ await ascendingState!.loadMore();
+ });
+
+ expect(screen.getByTestId("ascending-query").textContent).toBe("base|middle|live");
+ });
+});
+describe("message continuation deletion isolation", () => {
+ registerIsolationLifecycle();
+
+ it("replays deletions received during continuation before committing the page", async () => {
+ const continuationPage = deferred();
+ let messagePage = 0;
+ vi.stubGlobal(
+ "fetch",
+ vi.fn((input: RequestInfo | URL) => {
+ const url = String(input);
+ if (url.endsWith(BINDING_PATH_SUFFIX)) {
+ return Promise.resolve(
+ response({
+ bindingToken: "binding-1",
+ generation: 7,
+ expiresAt: FAR_FUTURE,
+ }),
+ );
+ }
+ messagePage += 1;
+ if (messagePage === 1) {
+ return Promise.resolve(
+ response({
+ messages: [message("message-base", "base", SNAPSHOT_CREATED_AT, "agent")],
+ hasMore: true,
+ cursor: "cursor-1",
+ }),
+ );
+ }
+ return continuationPage.promise;
+ }),
+ );
+ render(
+
+
+ ,
+ );
+ await waitFor(() => expect(ascendingState?.hasMore).toBe(true));
+
+ let loadMore!: Promise;
+ await act(async () => {
+ loadMore = ascendingState!.loadMore();
+ await waitFor(() => expect(messagePage).toBe(2));
+ });
+ act(() => transport.listener?.(liveMessageDeletedEvent(1, "message-page")));
+ continuationPage.resolve(
+ response({
+ messages: [message("message-page", "deleted page row", "2026-09-07T12:01:00Z", "agent")],
+ hasMore: false,
+ cursor: null,
+ }),
+ );
+ await act(async () => {
+ await loadMore;
+ });
+
+ expect(screen.getByTestId("ascending-query").textContent).toBe("base");
+ });
+});
diff --git a/apps/web/lib/plugins/conversation-host.test.tsx b/apps/web/lib/plugins/conversation-host.test.tsx
new file mode 100644
index 0000000000..760b12178c
--- /dev/null
+++ b/apps/web/lib/plugins/conversation-host.test.tsx
@@ -0,0 +1,1272 @@
+/* eslint-disable max-lines,sonarjs/no-duplicate-string,max-lines-per-function -- This integration fixture covers the full conversation lifecycle with many fixture literals. */
+import { act, cleanup, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { RawSessionEvent } from "@/lib/ws/client";
+import type { PluginSessionMessagesState, PluginSessionTurnsState } from "./types";
+import { PluginConversationScopeProvider, pluginConversationApi } from "./conversation-host";
+
+const transport = vi.hoisted(() => ({
+ request: vi.fn(),
+ listener: null as ((event: RawSessionEvent) => void) | null,
+ statusListener: null as ((status: "connected" | "disconnected") => void) | null,
+}));
+
+vi.mock("@/lib/config", () => ({ getBackendConfig: () => ({ apiBaseUrl: "http://host" }) }));
+vi.mock("@/lib/ws/connection", () => ({
+ getWebSocketClient: () => ({
+ request: transport.request,
+ onRawSessionEvent(listener: (event: RawSessionEvent) => void) {
+ transport.listener = listener;
+ return () => {
+ if (transport.listener === listener) transport.listener = null;
+ };
+ },
+ onConnectionStatus(listener: (status: "connected" | "disconnected") => void) {
+ transport.statusListener = listener;
+ return () => {
+ if (transport.statusListener === listener) transport.statusListener = null;
+ };
+ },
+ }),
+}));
+
+let currentState: PluginSessionMessagesState | null = null;
+let currentTurnsState: PluginSessionTurnsState | null = null;
+const SESSION_SUBSCRIBE_ACTION = "session.subscribe";
+const SESSION_ACK_ACTION = "session.ack";
+const BINDING_PATH_SUFFIX = "/conversation/binding";
+const FAR_FUTURE_EXPIRY = "2099-01-01T00:00:00Z";
+const MESSAGE_CREATED_AT = "2026-09-07T12:00:00Z";
+const SESSION_REMOVED_EVENT = "session.removed";
+
+function Harness({ sessionId, taskId }: { sessionId: string | null; taskId?: string | null }) {
+ currentState = pluginConversationApi.useSessionMessages({
+ sessionId,
+ taskId,
+ authorTypes: ["user"],
+ sort: "desc",
+ pageSize: 1,
+ });
+ return (
+
+
+ {currentState.messages.map((message) => message.content).join("|")}
+
+ {String(currentState.removed)}
+ {currentState.error?.code ?? ""}
+
+ );
+}
+
+function TurnsHarness({ sessionId, taskId }: { sessionId: string | null; taskId?: string | null }) {
+ currentTurnsState = pluginConversationApi.useSessionTurns(sessionId, taskId);
+ return (
+
+ {currentTurnsState.turns.map((turn) => turn.id).join("|")}
+ {String(currentTurnsState.removed)}
+ {currentTurnsState.error?.code ?? ""}
+
+ );
+}
+
+function renderTurnsHarness(sessionId: string | null, taskId?: string | null) {
+ return render(
+
+
+ ,
+ );
+}
+
+function renderHarness(sessionId: string | null, taskId?: string | null) {
+ return render(
+
+
+ ,
+ );
+}
+
+function response(body: unknown, status = 200): Response {
+ return new Response(JSON.stringify(body), {
+ status,
+ headers: { "Content-Type": "application/json" },
+ });
+}
+const TEST_MESSAGE_ID = "message-1";
+const MESSAGE_ADDED_EVENT = "message.added";
+
+function requiredEventPayload(eventType: string): Record {
+ switch (eventType) {
+ case MESSAGE_ADDED_EVENT:
+ return {
+ message_id: TEST_MESSAGE_ID,
+ author_type: "user",
+ content: "",
+ created_at: MESSAGE_CREATED_AT,
+ };
+ case "message.updated":
+ return {
+ message_id: TEST_MESSAGE_ID,
+ author_type: "user",
+ content: "",
+ created_at: MESSAGE_CREATED_AT,
+ updated_at: MESSAGE_CREATED_AT,
+ };
+ case "message.deleted":
+ return { message_id: TEST_MESSAGE_ID };
+ case "session.turn.started":
+ return { id: "turn-1", started_at: MESSAGE_CREATED_AT };
+ case "session.turn.completed":
+ return {
+ id: "turn-1",
+ started_at: MESSAGE_CREATED_AT,
+ completed_at: MESSAGE_CREATED_AT,
+ updated_at: MESSAGE_CREATED_AT,
+ };
+ default:
+ return {};
+ }
+}
+
+function event(
+ sequence: number,
+ eventType: string,
+ payload: Record,
+ taskId: string | null = "task-1",
+): RawSessionEvent {
+ const requiredPayload = requiredEventPayload(eventType);
+ return {
+ type: "session.event",
+ protocol_version: 1,
+ event_type: eventType,
+ session_id: "session-1",
+ task_id: taskId,
+ sequence,
+ event_id: `event-${sequence}`,
+ payload: {
+ session_id: "session-1",
+ ...(taskId !== null ? { task_id: taskId } : {}),
+ ...requiredPayload,
+ ...payload,
+ type: eventType,
+ },
+ };
+}
+
+beforeEach(() => {
+ currentState = null;
+ currentTurnsState = null;
+ transport.listener = null;
+ transport.statusListener = null;
+ transport.request.mockReset();
+ transport.request.mockImplementation((action: string) => {
+ if (action === SESSION_SUBSCRIBE_ACTION) {
+ return Promise.resolve({
+ success: true,
+ snapshot_token: "snapshot-1",
+ resume_token: "resume-0",
+ consumer_id: "consumer-1",
+ event_watermark: 0,
+ expires_at: FAR_FUTURE_EXPIRY,
+ result: "fresh",
+ });
+ }
+ if (action === SESSION_ACK_ACTION) {
+ return Promise.resolve({ success: true, resume_token: "resume-next" });
+ }
+ return Promise.resolve({ success: true });
+ });
+});
+afterEach(() => {
+ cleanup();
+ vi.unstubAllGlobals();
+});
+describe("plugin conversation Host facade", () => {
+ it("keeps nullable sessions empty without transport activity", async () => {
+ const fetchMock = vi.fn();
+ vi.stubGlobal("fetch", fetchMock);
+
+ renderHarness(null);
+
+ expect(screen.getByTestId("messages").textContent).toBe("");
+ expect(currentState?.hasMore).toBe(false);
+ expect(currentState?.hydrated).toBe(false);
+ expect(await currentState?.loadMore()).toBe(0);
+ expect(fetchMock).not.toHaveBeenCalled();
+ expect(transport.request).not.toHaveBeenCalled();
+ });
+
+ it("retries initial binding setup after a transient failure", async () => {
+ let bindingFetches = 0;
+ const fetchMock = vi.fn((input: RequestInfo | URL) => {
+ if (String(input).endsWith(BINDING_PATH_SUFFIX)) {
+ bindingFetches += 1;
+ if (bindingFetches === 1) {
+ return Promise.resolve(
+ response(
+ { error: { code: "upstream_failure", message: "temporary", retryable: true } },
+ 503,
+ ),
+ );
+ }
+ return Promise.resolve(
+ response({ bindingToken: "binding-2", generation: 7, expiresAt: FAR_FUTURE_EXPIRY }),
+ );
+ }
+ return Promise.resolve(response({ messages: [], hasMore: false, cursor: null }));
+ });
+ vi.stubGlobal("fetch", fetchMock);
+ renderHarness("session-1");
+ await waitFor(() => expect(currentState?.error?.retryable).toBe(true));
+
+ act(() => currentState?.retry());
+
+ await waitFor(() => expect(currentState?.hydrated).toBe(true));
+ expect(bindingFetches).toBe(2);
+ });
+
+ it("retries initial ordered subscription after a transient failure", async () => {
+ const fetchMock = vi.fn((input: RequestInfo | URL) =>
+ String(input).endsWith(BINDING_PATH_SUFFIX)
+ ? Promise.resolve(
+ response({ bindingToken: "binding-1", generation: 7, expiresAt: FAR_FUTURE_EXPIRY }),
+ )
+ : Promise.resolve(response({ messages: [], hasMore: false, cursor: null })),
+ );
+ vi.stubGlobal("fetch", fetchMock);
+ transport.request.mockRejectedValueOnce(new Error("temporary subscribe failure"));
+ renderHarness("session-1");
+ await waitFor(() => expect(currentState?.error?.retryable).toBe(true));
+
+ act(() => currentState?.retry());
+
+ await waitFor(() => expect(currentState?.hydrated).toBe(true));
+ expect(
+ transport.request.mock.calls.filter(([action]) => action === SESSION_SUBSCRIBE_ACTION),
+ ).toHaveLength(2);
+ });
+
+ it("commits the authorized snapshot before projecting and acknowledging ordered live events", async () => {
+ const fetchMock = vi.fn((input: RequestInfo | URL) => {
+ const url = String(input);
+ if (url.endsWith(BINDING_PATH_SUFFIX)) {
+ return Promise.resolve(
+ response({ bindingToken: "binding-1", generation: 7, expiresAt: FAR_FUTURE_EXPIRY }),
+ );
+ }
+ return Promise.resolve(
+ response({
+ messages: [
+ {
+ id: "message-1",
+ taskId: "task-1",
+ sessionId: "session-1",
+ authorType: "user",
+ type: "message",
+ content: "original",
+ createdAt: MESSAGE_CREATED_AT,
+ updatedAt: MESSAGE_CREATED_AT,
+ },
+ ],
+ hasMore: false,
+ cursor: null,
+ }),
+ );
+ });
+ vi.stubGlobal("fetch", fetchMock);
+
+ renderHarness("session-1");
+ await waitFor(() => expect(screen.getByTestId("messages").textContent).toBe("original"));
+ expect(currentState?.hydrated).toBe(true);
+
+ act(() => {
+ transport.listener?.(
+ event(1, "message.updated", {
+ message_id: "message-1",
+ author_type: "user",
+ content: "updated",
+ message_type: "message",
+ created_at: MESSAGE_CREATED_AT,
+ updated_at: "2026-09-07T12:01:00Z",
+ }),
+ );
+ });
+ expect(screen.getByTestId("messages").textContent).toBe("updated");
+ await waitFor(() =>
+ expect(transport.request).toHaveBeenCalledWith(
+ SESSION_ACK_ACTION,
+ expect.objectContaining({ sequence: 1 }),
+ ),
+ );
+ await act(async () => {
+ await Promise.resolve();
+ });
+ const initialConsumerId = "consumer-1";
+
+ act(() => {
+ transport.statusListener?.("disconnected");
+ });
+ act(() => {
+ transport.statusListener?.("connected");
+ });
+ await waitFor(() =>
+ expect(transport.request).toHaveBeenCalledWith(
+ SESSION_SUBSCRIBE_ACTION,
+ expect.objectContaining({
+ consumer_id: initialConsumerId,
+ last_seen_sequence: 1,
+ resume_token: "resume-next",
+ }),
+ ),
+ );
+ act(() => {
+ transport.listener?.(event(2, "message.deleted", { message_id: "message-1" }));
+ transport.listener?.(event(3, SESSION_REMOVED_EVENT, {}, null));
+ });
+ expect(screen.getByTestId("messages").textContent).toBe("updated");
+ expect(screen.getByTestId("removed").textContent).toBe("true");
+ expect(currentState?.hasMore).toBe(false);
+ });
+
+ it("recovers an expired continuation without remount and continues the load", async () => {
+ let subscribeCount = 0;
+ transport.request.mockImplementation((action: string) => {
+ if (action === SESSION_SUBSCRIBE_ACTION) {
+ subscribeCount += 1;
+ return Promise.resolve({
+ success: true,
+ snapshot_token: `snapshot-${subscribeCount}`,
+ resume_token: `resume-${subscribeCount}`,
+ consumer_id: `consumer-${subscribeCount}`,
+ event_watermark: 0,
+ expires_at: subscribeCount === 1 ? "2020-01-01T00:00:00Z" : FAR_FUTURE_EXPIRY,
+ result: "fresh",
+ });
+ }
+ if (action === SESSION_ACK_ACTION) {
+ return Promise.resolve({ success: true, resume_token: "resume-next" });
+ }
+ return Promise.resolve({ success: true });
+ });
+
+ let messagePages = 0;
+ const fetchMock = vi.fn((input: RequestInfo | URL) => {
+ const url = String(input);
+ if (url.endsWith(BINDING_PATH_SUFFIX)) {
+ return Promise.resolve(
+ response({ bindingToken: "binding-1", generation: 7, expiresAt: FAR_FUTURE_EXPIRY }),
+ );
+ }
+ if (url.endsWith("/conversation/continuation/renew")) {
+ return Promise.resolve(
+ response({ error: { code: "invalid_query", message: "expired", retryable: false } }, 400),
+ );
+ }
+ messagePages += 1;
+ const cursor = new URL(url).searchParams.get("cursor");
+ if (!cursor) {
+ return Promise.resolve(
+ response({
+ messages: [
+ {
+ id: "message-newest",
+ taskId: "task-1",
+ sessionId: "session-1",
+ authorType: "user",
+ type: "message",
+ content: `newest-page-${messagePages}`,
+ createdAt: MESSAGE_CREATED_AT,
+ updatedAt: MESSAGE_CREATED_AT,
+ },
+ ],
+ hasMore: true,
+ cursor: messagePages === 1 ? "cursor-expired" : "cursor-fresh",
+ }),
+ );
+ }
+ expect(cursor).toBe("cursor-fresh");
+ return Promise.resolve(
+ response({
+ messages: [
+ {
+ id: "message-older",
+ taskId: "task-1",
+ sessionId: "session-1",
+ authorType: "user",
+ type: "message",
+ content: "older-page",
+ createdAt: "2026-09-07T11:59:00Z",
+ updatedAt: "2026-09-07T11:59:00Z",
+ },
+ ],
+ hasMore: false,
+ cursor: null,
+ }),
+ );
+ });
+ vi.stubGlobal("fetch", fetchMock);
+
+ renderHarness("session-1");
+ await waitFor(() => expect(currentState?.hasMore).toBe(true));
+ await expect(currentState?.loadMore()).resolves.toBe(1);
+
+ expect(subscribeCount).toBe(2);
+ expect(fetchMock).not.toHaveBeenCalledWith(
+ expect.stringContaining("/conversation/continuation/renew"),
+ expect.anything(),
+ );
+ await waitFor(() => expect(screen.getByTestId("messages").textContent).toContain("older-page"));
+ });
+});
+
+describe("strict ordered event validation poisons instead of projecting", () => {
+ function stubEmptySnapshot() {
+ const fetchMock = vi.fn((input: RequestInfo | URL) =>
+ String(input).endsWith(BINDING_PATH_SUFFIX)
+ ? Promise.resolve(
+ response({ bindingToken: "binding-1", generation: 7, expiresAt: FAR_FUTURE_EXPIRY }),
+ )
+ : Promise.resolve(response({ messages: [], hasMore: false, cursor: null })),
+ );
+ vi.stubGlobal("fetch", fetchMock);
+ }
+
+ it("does not treat a removal with a mismatched payload session_id as terminal", async () => {
+ stubEmptySnapshot();
+ renderHarness("session-1");
+ await waitFor(() => expect(currentState?.hydrated).toBe(true));
+
+ act(() => {
+ transport.listener?.(event(1, SESSION_REMOVED_EVENT, { session_id: "session-other" }, null));
+ });
+ expect(screen.getByTestId("removed").textContent).toBe("false");
+ await waitFor(() =>
+ expect(transport.request).toHaveBeenCalledWith(
+ SESSION_SUBSCRIBE_ACTION,
+ expect.objectContaining({
+ replace_cursor: true,
+ consumer_kind: "plugin",
+ plugin_id: "plugin-history",
+ session_id: "session-1",
+ }),
+ ),
+ );
+ expect(screen.getByTestId("removed").textContent).toBe("false");
+ });
+
+ it("projects attachment-only messages with empty content through add and update", async () => {
+ stubEmptySnapshot();
+ renderHarness("session-1");
+ await waitFor(() => expect(currentState?.hydrated).toBe(true));
+
+ act(() => {
+ transport.listener?.(
+ event(1, "message.added", {
+ message_id: "message-attachment-only",
+ content: "",
+ created_at: MESSAGE_CREATED_AT,
+ }),
+ );
+ });
+ expect(currentState?.messages).toHaveLength(1);
+ expect(currentState?.messages[0]?.content).toBe("");
+
+ act(() => {
+ transport.listener?.(
+ event(2, "message.updated", {
+ message_id: "message-attachment-only",
+ content: "",
+ created_at: MESSAGE_CREATED_AT,
+ updated_at: "2026-09-07T12:01:00Z",
+ }),
+ );
+ });
+ expect(currentState?.messages).toHaveLength(1);
+ expect(currentState?.messages[0]).toMatchObject({
+ id: "message-attachment-only",
+ content: "",
+ updatedAt: "2026-09-07T12:01:00Z",
+ });
+ });
+
+ it("does not let a retry page overwrite a live event projected mid-fetch", async () => {
+ let resolveRetryPage: ((value: Response) => void) | undefined;
+ const retryPage = new Promise((resolve) => {
+ resolveRetryPage = resolve;
+ });
+ let messageFetches = 0;
+ const fetchMock = vi.fn((input: RequestInfo | URL) => {
+ const url = String(input);
+ if (url.endsWith(BINDING_PATH_SUFFIX)) {
+ return Promise.resolve(
+ response({ bindingToken: "binding-1", generation: 7, expiresAt: FAR_FUTURE_EXPIRY }),
+ );
+ }
+ messageFetches += 1;
+ if (messageFetches === 1) {
+ return Promise.resolve(
+ response({
+ messages: [
+ {
+ id: "message-original",
+ taskId: "task-1",
+ sessionId: "session-1",
+ authorType: "user",
+ type: "message",
+ content: "original",
+ createdAt: MESSAGE_CREATED_AT,
+ updatedAt: MESSAGE_CREATED_AT,
+ },
+ ],
+ hasMore: true,
+ cursor: "cursor-1",
+ }),
+ );
+ }
+ if (messageFetches === 2) {
+ return Promise.reject(new TypeError("network down"));
+ }
+ return retryPage;
+ });
+ vi.stubGlobal("fetch", fetchMock);
+ renderHarness("session-1");
+ await waitFor(() => expect(screen.getByTestId("messages").textContent).toBe("original"));
+
+ await expect(currentState?.loadMore()).rejects.toBeTruthy();
+ await waitFor(() => expect(currentState?.error?.retryable).toBe(true));
+
+ act(() => currentState?.retry());
+ await waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(3));
+
+ // A live update lands while the retry page is still in flight.
+ act(() => {
+ transport.listener?.(
+ event(1, "message.added", {
+ message_id: "message-live",
+ content: "live-during-retry",
+ created_at: "2026-09-07T12:00:01Z",
+ updated_at: "2026-09-07T12:00:01Z",
+ }),
+ );
+ });
+ expect(screen.getByTestId("messages").textContent).toBe("");
+
+ await act(async () => {
+ resolveRetryPage?.(
+ response({
+ messages: [
+ {
+ id: "message-original",
+ taskId: "task-1",
+ sessionId: "session-1",
+ authorType: "user",
+ type: "message",
+ content: "original",
+ createdAt: MESSAGE_CREATED_AT,
+ updatedAt: MESSAGE_CREATED_AT,
+ },
+ ],
+ hasMore: false,
+ cursor: null,
+ }),
+ );
+ await Promise.resolve();
+ });
+ await waitFor(() =>
+ expect(screen.getByTestId("messages").textContent).toContain("live-during-retry"),
+ );
+ expect(screen.getByTestId("messages").textContent).toContain("original");
+ });
+
+ it("projects live events from the subscribe watermark, not sequence one", async () => {
+ const fetchMock = vi.fn((input: RequestInfo | URL) =>
+ String(input).endsWith(BINDING_PATH_SUFFIX)
+ ? Promise.resolve(
+ response({ bindingToken: "binding-1", generation: 7, expiresAt: FAR_FUTURE_EXPIRY }),
+ )
+ : Promise.resolve(response({ messages: [], hasMore: false, cursor: null })),
+ );
+ vi.stubGlobal("fetch", fetchMock);
+ // An existing non-empty session subscribes at event_watermark 3; live
+ // frames therefore start at sequence 4 and must not park waiting for 1.
+ transport.request.mockImplementation((action: string) => {
+ if (action === SESSION_SUBSCRIBE_ACTION) {
+ return Promise.resolve({
+ success: true,
+ snapshot_token: "snapshot-1",
+ resume_token: "resume-0",
+ consumer_id: "consumer-1",
+ event_watermark: 3,
+ expires_at: FAR_FUTURE_EXPIRY,
+ result: "fresh",
+ });
+ }
+ if (action === SESSION_ACK_ACTION) {
+ return Promise.resolve({ success: true, resume_token: "resume-next" });
+ }
+ return Promise.resolve({ success: true });
+ });
+ renderHarness("session-1");
+ await waitFor(() => expect(currentState?.hydrated).toBe(true));
+
+ act(() => {
+ transport.listener?.(
+ event(4, "message.added", { message_id: "message-4", content: "live-four" }),
+ );
+ });
+ expect(screen.getByTestId("messages").textContent).toBe("live-four");
+ });
+
+ it("accepts session.removed whose task_id differs from the session task", async () => {
+ stubEmptySnapshot();
+ renderHarness("session-1");
+ await waitFor(() => expect(currentState?.hydrated).toBe(true));
+
+ act(() => {
+ transport.listener?.(event(1, SESSION_REMOVED_EVENT, { task_id: "task-moved" }, null));
+ });
+ expect(screen.getByTestId("removed").textContent).toBe("true");
+ });
+
+ it("does not resurrect rows from events delivered after terminal removal", async () => {
+ stubEmptySnapshot();
+ renderHarness("session-1");
+ await waitFor(() => expect(currentState?.hydrated).toBe(true));
+
+ act(() => {
+ transport.listener?.(event(1, SESSION_REMOVED_EVENT, {}, null));
+ transport.listener?.(event(2, "message.added", { message_id: "late", content: "late" }));
+ });
+ expect(screen.getByTestId("removed").textContent).toBe("true");
+ expect(screen.getByTestId("messages").textContent).toBe("");
+ });
+
+ it("retains projected messages when session removal follows message deletions", async () => {
+ stubEmptySnapshot();
+ renderHarness("session-1");
+ await waitFor(() => expect(currentState?.hydrated).toBe(true));
+
+ act(() => {
+ transport.listener?.(
+ event(1, MESSAGE_ADDED_EVENT, {
+ message_id: "message-terminal",
+ content: "retained after removal",
+ }),
+ );
+ });
+ await waitFor(() =>
+ expect(screen.getByTestId("messages").textContent).toBe("retained after removal"),
+ );
+
+ act(() => {
+ transport.listener?.(event(2, "message.deleted", { message_id: "message-terminal" }));
+ transport.listener?.(event(3, SESSION_REMOVED_EVENT, {}, null));
+ });
+
+ expect(screen.getByTestId("messages").textContent).toBe("retained after removal");
+ expect(screen.getByTestId("removed").textContent).toBe("true");
+ });
+
+ it("recovers through a durable rebind after a message with a missing required id", async () => {
+ stubEmptySnapshot();
+ renderHarness("session-1");
+ await waitFor(() => expect(currentState?.hydrated).toBe(true));
+
+ act(() => {
+ transport.listener?.(event(1, "message.added", { message_id: "", content: "no-id" }));
+ });
+ expect(screen.getByTestId("messages").textContent).toBe("");
+ await waitFor(() =>
+ expect(transport.request).toHaveBeenCalledWith(
+ SESSION_SUBSCRIBE_ACTION,
+ expect.objectContaining({ replace_cursor: true }),
+ ),
+ );
+ await act(async () => {
+ await Promise.resolve();
+ });
+
+ act(() => {
+ transport.listener?.(event(1, SESSION_REMOVED_EVENT, {}, null));
+ });
+ expect(screen.getByTestId("removed").textContent).toBe("true");
+ });
+});
+it("does not fetch after terminal removal even through a captured loadMore callback", async () => {
+ const fetchMock = vi.fn((input: RequestInfo | URL) =>
+ String(input).endsWith(BINDING_PATH_SUFFIX)
+ ? Promise.resolve(
+ response({ bindingToken: "binding-1", generation: 7, expiresAt: FAR_FUTURE_EXPIRY }),
+ )
+ : Promise.resolve(response({ messages: [], hasMore: true, cursor: "cursor-1" })),
+ );
+ vi.stubGlobal("fetch", fetchMock);
+ renderHarness("session-1");
+ await waitFor(() => expect(currentState?.hasMore).toBe(true));
+ const loadMore = currentState?.loadMore;
+ act(() => transport.listener?.(event(1, SESSION_REMOVED_EVENT, {}, null)));
+ await expect(loadMore?.()).resolves.toBe(0);
+ expect(fetchMock).toHaveBeenCalledTimes(2);
+});
+
+it("commits terminal removal while the initial snapshot is still pending", async () => {
+ let resolveSnapshot: ((value: Response) => void) | undefined;
+ const snapshot = new Promise((resolve) => {
+ resolveSnapshot = resolve;
+ });
+ const fetchMock = vi.fn((input: RequestInfo | URL) => {
+ if (String(input).endsWith(BINDING_PATH_SUFFIX)) {
+ return Promise.resolve(
+ response({ bindingToken: "binding-1", generation: 7, expiresAt: FAR_FUTURE_EXPIRY }),
+ );
+ }
+ return snapshot;
+ });
+ vi.stubGlobal("fetch", fetchMock);
+ renderHarness("session-1");
+ await waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2));
+
+ act(() => {
+ transport.listener?.(event(1, SESSION_REMOVED_EVENT, {}, null));
+ });
+ expect(screen.getByTestId("removed").textContent).toBe("true");
+
+ await act(async () => {
+ resolveSnapshot?.(
+ response({
+ messages: [
+ {
+ id: "message-late",
+ taskId: "task-1",
+ sessionId: "session-1",
+ authorType: "user",
+ type: "message",
+ content: "must not resurrect",
+ createdAt: MESSAGE_CREATED_AT,
+ updatedAt: MESSAGE_CREATED_AT,
+ },
+ ],
+ hasMore: true,
+ cursor: "late-cursor",
+ }),
+ );
+ await snapshot;
+ });
+ expect(screen.getByTestId("removed").textContent).toBe("true");
+ expect(screen.getByTestId("error").textContent).toBe("");
+ expect(screen.getByTestId("messages").textContent).toBe("");
+});
+it("replays add, update, and delete events after a blocked snapshot without resurrection", async () => {
+ let resolveSnapshot: ((value: Response) => void) | undefined;
+ const snapshot = new Promise((resolve) => {
+ resolveSnapshot = resolve;
+ });
+ const fetchMock = vi.fn((input: RequestInfo | URL) => {
+ if (String(input).endsWith(BINDING_PATH_SUFFIX)) {
+ return Promise.resolve(
+ response({ bindingToken: "binding-1", generation: 7, expiresAt: FAR_FUTURE_EXPIRY }),
+ );
+ }
+ return snapshot;
+ });
+ vi.stubGlobal("fetch", fetchMock);
+ renderHarness("session-1");
+ await waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2));
+
+ act(() => {
+ transport.listener?.(
+ event(1, MESSAGE_ADDED_EVENT, {
+ message_id: "message-new",
+ author_type: "user",
+ content: "temporary",
+ message_type: "message",
+ created_at: "2026-09-07T12:02:00Z",
+ }),
+ );
+ transport.listener?.(
+ event(2, "message.updated", {
+ message_id: "message-base",
+ author_type: "user",
+ content: "updated",
+ message_type: "message",
+ created_at: MESSAGE_CREATED_AT,
+ updated_at: "2026-09-07T12:03:00Z",
+ }),
+ );
+ transport.listener?.(event(3, "message.deleted", { message_id: "message-new" }));
+ });
+ expect(screen.getByTestId("messages").textContent).toBe("");
+
+ await act(async () => {
+ resolveSnapshot?.(
+ response({
+ messages: [
+ {
+ id: "message-base",
+ taskId: "task-1",
+ sessionId: "session-1",
+ authorType: "user",
+ type: "message",
+ content: "original",
+ createdAt: MESSAGE_CREATED_AT,
+ updatedAt: MESSAGE_CREATED_AT,
+ },
+ ],
+ hasMore: false,
+ cursor: null,
+ }),
+ );
+ await snapshot;
+ });
+
+ expect(screen.getByTestId("messages").textContent).toBe("updated");
+ await waitFor(() =>
+ expect(transport.request).toHaveBeenCalledWith(
+ SESSION_ACK_ACTION,
+ expect.objectContaining({ sequence: 3 }),
+ ),
+ );
+});
+it("keeps turns terminal when removal wins the initial snapshot race", async () => {
+ let resolveSnapshot: ((value: Response) => void) | undefined;
+ const snapshot = new Promise((resolve) => {
+ resolveSnapshot = resolve;
+ });
+ const fetchMock = vi.fn((input: RequestInfo | URL) => {
+ if (String(input).endsWith(BINDING_PATH_SUFFIX)) {
+ return Promise.resolve(
+ response({ bindingToken: "binding-1", generation: 7, expiresAt: FAR_FUTURE_EXPIRY }),
+ );
+ }
+ return snapshot;
+ });
+ vi.stubGlobal("fetch", fetchMock);
+ renderTurnsHarness("session-1");
+ await waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2));
+
+ act(() => {
+ transport.listener?.(event(1, SESSION_REMOVED_EVENT, {}, null));
+ });
+ expect(screen.getByTestId("turns-removed").textContent).toBe("true");
+
+ await act(async () => {
+ resolveSnapshot?.(
+ response({
+ turns: [
+ {
+ id: "turn-late",
+ taskId: "task-1",
+ sessionId: "session-1",
+ startedAt: MESSAGE_CREATED_AT,
+ updatedAt: MESSAGE_CREATED_AT,
+ },
+ ],
+ }),
+ );
+ await snapshot;
+ });
+ expect(screen.getByTestId("turns-removed").textContent).toBe("true");
+ expect(screen.getByTestId("turns-error").textContent).toBe("");
+ expect(screen.getByTestId("turns").textContent).toBe("");
+});
+describe("plugin conversation ordering and binding lifecycle", () => {
+ it("holds a forward sequence gap and drains events when the missing sequence arrives", async () => {
+ const fetchMock = vi.fn((input: RequestInfo | URL) => {
+ if (String(input).endsWith(BINDING_PATH_SUFFIX)) {
+ return Promise.resolve(
+ response({ bindingToken: "binding-1", generation: 7, expiresAt: FAR_FUTURE_EXPIRY }),
+ );
+ }
+ return Promise.resolve(response({ messages: [], hasMore: false, cursor: null }));
+ });
+ vi.stubGlobal("fetch", fetchMock);
+ renderHarness("session-1");
+ await waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2));
+
+ act(() => {
+ transport.listener?.(
+ event(2, MESSAGE_ADDED_EVENT, {
+ message_id: "message-two",
+ author_type: "user",
+ content: "second",
+ message_type: "message",
+ created_at: "2026-09-07T12:02:00Z",
+ }),
+ );
+ });
+ expect(screen.getByTestId("messages").textContent).toBe("");
+ expect(transport.request.mock.calls.some(([action]) => action === SESSION_ACK_ACTION)).toBe(
+ false,
+ );
+
+ act(() => {
+ transport.listener?.(
+ event(1, MESSAGE_ADDED_EVENT, {
+ message_id: "message-one",
+ author_type: "user",
+ content: "first",
+ message_type: "message",
+ created_at: "2026-09-07T12:01:00Z",
+ }),
+ );
+ });
+
+ expect(screen.getByTestId("messages").textContent).toBe("second|first");
+ await waitFor(() =>
+ expect(transport.request).toHaveBeenCalledWith(
+ SESSION_ACK_ACTION,
+ expect.objectContaining({ sequence: 2 }),
+ ),
+ );
+ });
+
+ it("refreshes a loader binding and atomically replaces a superseded generation", async () => {
+ let bindingReads = 0;
+ const fetchMock = vi.fn((input: RequestInfo | URL, init?: RequestInit) => {
+ if (String(input).endsWith(BINDING_PATH_SUFFIX)) {
+ bindingReads += 1;
+ const expiresAt =
+ bindingReads === 1 ? new Date(Date.now() + 60_000).toISOString() : FAR_FUTURE_EXPIRY;
+ return Promise.resolve(
+ response({
+ bindingToken: `binding-${bindingReads}`,
+ generation: bindingReads + 6,
+ expiresAt,
+ }),
+ );
+ }
+ expect(new Headers(init?.headers).get("X-Kandev-Plugin-Binding")).toBe("binding-2");
+ return Promise.resolve(response({ messages: [], hasMore: false, cursor: null }));
+ });
+ vi.stubGlobal("fetch", fetchMock);
+
+ renderHarness("session-1");
+ await waitFor(() => expect(currentState?.loading).toBe(false));
+
+ expect(bindingReads).toBe(2);
+ const subscribeGenerations = transport.request.mock.calls
+ .filter(([action]) => action === SESSION_SUBSCRIBE_ACTION)
+ .map(([, request]) => request.generation);
+ expect(subscribeGenerations).toEqual([7, 8]);
+ expect(transport.request).toHaveBeenCalledWith(
+ "session.unsubscribe",
+ expect.objectContaining({ generation: 7 }),
+ );
+ });
+});
+
+it("atomically rebinds and replaces snapshots past a poison event", async () => {
+ let snapshotReads = 0;
+ let subscribes = 0;
+ transport.request.mockImplementation((action: string) => {
+ if (action === SESSION_SUBSCRIBE_ACTION) {
+ subscribes += 1;
+ return Promise.resolve({
+ success: true,
+ snapshot_token: `snapshot-${subscribes}`,
+ resume_token: `resume-${subscribes}`,
+ consumer_id: "consumer-1",
+ event_watermark: subscribes - 1,
+ expires_at: FAR_FUTURE_EXPIRY,
+ result: "fresh",
+ });
+ }
+ if (action === SESSION_ACK_ACTION) {
+ return Promise.resolve({ success: true, resume_token: "resume-next" });
+ }
+ return Promise.resolve({ success: true });
+ });
+ vi.stubGlobal(
+ "fetch",
+ vi.fn((input: RequestInfo | URL) => {
+ if (String(input).endsWith(BINDING_PATH_SUFFIX)) {
+ return Promise.resolve(
+ response({ bindingToken: "binding-1", generation: 7, expiresAt: FAR_FUTURE_EXPIRY }),
+ );
+ }
+ snapshotReads += 1;
+ return Promise.resolve(
+ response({
+ messages: [
+ {
+ id: "message-1",
+ taskId: "task-1",
+ sessionId: "session-1",
+ authorType: "user",
+ type: "message",
+ content: snapshotReads === 1 ? "before poison" : "after poison",
+ createdAt: MESSAGE_CREATED_AT,
+ updatedAt: MESSAGE_CREATED_AT,
+ },
+ ],
+ hasMore: false,
+ cursor: null,
+ }),
+ );
+ }),
+ );
+
+ renderHarness("session-1");
+ await waitFor(() => expect(screen.getByTestId("messages").textContent).toBe("before poison"));
+
+ act(() => transport.listener?.(event(1, "unknown.event", {})));
+
+ await waitFor(() => expect(screen.getByTestId("messages").textContent).toBe("after poison"));
+ expect(subscribes).toBe(2);
+ expect(transport.request.mock.calls.some(([action]) => action === SESSION_ACK_ACTION)).toBe(
+ false,
+ );
+});
+
+it("surfaces terminal removal after an earlier poison event without advancing ACK", async () => {
+ const fetchMock = vi.fn((input: RequestInfo | URL) => {
+ if (String(input).endsWith(BINDING_PATH_SUFFIX)) {
+ return Promise.resolve(
+ response({ bindingToken: "binding-1", generation: 7, expiresAt: FAR_FUTURE_EXPIRY }),
+ );
+ }
+ return Promise.resolve(response({ messages: [], hasMore: false, cursor: null }));
+ });
+ vi.stubGlobal("fetch", fetchMock);
+ renderHarness("session-1");
+ await waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2));
+
+ act(() => {
+ transport.listener?.(event(1, "unknown.event", {}));
+ transport.listener?.(event(2, SESSION_REMOVED_EVENT, {}, null));
+ });
+
+ expect(screen.getByTestId("removed").textContent).toBe("true");
+ expect(transport.request.mock.calls.some(([action]) => action === SESSION_ACK_ACTION)).toBe(
+ false,
+ );
+});
+
+describe("plugin conversation pagination", () => {
+ it("joins concurrent requests for one older-page continuation", async () => {
+ let page = 0;
+ const fetchMock = vi.fn((input: RequestInfo | URL) => {
+ const url = String(input);
+ if (url.endsWith(BINDING_PATH_SUFFIX)) {
+ return Promise.resolve(
+ response({ bindingToken: "binding-1", generation: 7, expiresAt: FAR_FUTURE_EXPIRY }),
+ );
+ }
+ page += 1;
+ return Promise.resolve(
+ response({
+ messages: [
+ {
+ id: `message-${page}`,
+ taskId: "task-1",
+ sessionId: "session-1",
+ authorType: "user",
+ type: "message",
+ content: `page-${page}`,
+ createdAt: `2026-09-07T12:0${page}:00Z`,
+ updatedAt: `2026-09-07T12:0${page}:00Z`,
+ },
+ ],
+ hasMore: page === 1,
+ cursor: page === 1 ? "cursor-1" : null,
+ }),
+ );
+ });
+ vi.stubGlobal("fetch", fetchMock);
+
+ renderHarness("session-1");
+ await waitFor(() => expect(currentState?.hasMore).toBe(true));
+ let counts: number[] = [];
+ const loadMore = currentState!.loadMore;
+ await act(async () => {
+ counts = await Promise.all([loadMore(), loadMore()]);
+ });
+
+ expect(page).toBe(2);
+ expect(counts).toEqual([1, 1]);
+ expect(screen.getByTestId("messages").textContent).toContain("page-2");
+ });
+});
+
+describe("ordered turns convergence", () => {
+ function stubTurnsFetch() {
+ const fetchMock = vi.fn((input: RequestInfo | URL) => {
+ const url = String(input);
+ if (url.endsWith(BINDING_PATH_SUFFIX)) {
+ return Promise.resolve(
+ response({ bindingToken: "binding-1", generation: 7, expiresAt: FAR_FUTURE_EXPIRY }),
+ );
+ }
+ return Promise.resolve(response({ turns: [], hasMore: false, cursor: null }));
+ });
+ vi.stubGlobal("fetch", fetchMock);
+ return fetchMock;
+ }
+
+ it("drops a turn from live state when session.turn.removed arrives", async () => {
+ stubTurnsFetch();
+ renderTurnsHarness("session-1");
+ await waitFor(() => expect(currentTurnsState?.hydrated).toBe(true));
+
+ act(() => {
+ transport.listener?.(
+ event(1, "session.turn.started", {
+ id: "turn-1",
+ started_at: MESSAGE_CREATED_AT,
+ completed_at: null,
+ created_at: MESSAGE_CREATED_AT,
+ updated_at: MESSAGE_CREATED_AT,
+ }),
+ );
+ transport.listener?.(
+ event(2, "session.turn.completed", {
+ id: "turn-1",
+ started_at: MESSAGE_CREATED_AT,
+ completed_at: MESSAGE_CREATED_AT,
+ created_at: MESSAGE_CREATED_AT,
+ updated_at: MESSAGE_CREATED_AT,
+ }),
+ );
+ });
+ await waitFor(() => expect(currentTurnsState?.turns).toHaveLength(1));
+
+ act(() => {
+ transport.listener?.(event(3, "session.turn.removed", { id: "turn-1" }));
+ });
+ expect(currentTurnsState?.turns).toHaveLength(0);
+ expect(currentTurnsState?.hydrated).toBe(true);
+ expect(screen.getByTestId("turns-removed").textContent).toBe("false");
+ });
+
+ it("retains projected turns when session removal follows turn deletions", async () => {
+ stubTurnsFetch();
+ renderTurnsHarness("session-1");
+ await waitFor(() => expect(currentTurnsState?.hydrated).toBe(true));
+
+ act(() => {
+ transport.listener?.(
+ event(1, "session.turn.started", {
+ id: "turn-terminal",
+ started_at: MESSAGE_CREATED_AT,
+ updated_at: MESSAGE_CREATED_AT,
+ }),
+ );
+ transport.listener?.(
+ event(2, "session.turn.completed", {
+ id: "turn-terminal",
+ started_at: MESSAGE_CREATED_AT,
+ completed_at: MESSAGE_CREATED_AT,
+ updated_at: MESSAGE_CREATED_AT,
+ }),
+ );
+ });
+ await waitFor(() => expect(currentTurnsState?.turns).toHaveLength(1));
+
+ act(() => {
+ transport.listener?.(event(3, "session.turn.removed", { id: "turn-terminal" }));
+ transport.listener?.(event(4, SESSION_REMOVED_EVENT, {}, null));
+ });
+
+ expect(currentTurnsState?.turns.map((turn) => turn.id)).toEqual(["turn-terminal"]);
+ expect(screen.getByTestId("turns-removed").textContent).toBe("true");
+ });
+
+ it.each([
+ { name: "inherited task", selectedTaskId: undefined, removalTaskId: "task-2", removed: false },
+ { name: "explicit task", selectedTaskId: "task-1", removalTaskId: "task-1", removed: true },
+ { name: "session-wide scope", selectedTaskId: null, removalTaskId: "task-2", removed: true },
+ ])(
+ "applies turn removals only within $name",
+ async ({ selectedTaskId, removalTaskId, removed }) => {
+ stubTurnsFetch();
+ renderTurnsHarness("session-1", selectedTaskId);
+ await waitFor(() => expect(currentTurnsState?.hydrated).toBe(true));
+ act(() => {
+ transport.listener?.(
+ event(1, "session.turn.started", {
+ id: "turn-1",
+ started_at: MESSAGE_CREATED_AT,
+ completed_at: null,
+ created_at: MESSAGE_CREATED_AT,
+ updated_at: MESSAGE_CREATED_AT,
+ }),
+ );
+ });
+ await waitFor(() => expect(currentTurnsState?.turns).toHaveLength(1));
+
+ act(() => {
+ transport.listener?.(event(2, "session.turn.removed", { id: "turn-1" }, removalTaskId));
+ });
+
+ expect(currentTurnsState?.turns).toHaveLength(removed ? 0 : 1);
+ },
+ );
+
+ it("does not let a retry turns page overwrite a live completion mid-fetch", async () => {
+ let resolveRetry: ((value: Response) => void) | undefined;
+ const retryPage = new Promise((resolve) => {
+ resolveRetry = resolve;
+ });
+ let turnFetches = 0;
+ const fetchMock = vi.fn((input: RequestInfo | URL) => {
+ const url = String(input);
+ if (url.endsWith(BINDING_PATH_SUFFIX)) {
+ return Promise.resolve(
+ response({ bindingToken: "binding-1", generation: 7, expiresAt: FAR_FUTURE_EXPIRY }),
+ );
+ }
+ turnFetches += 1;
+ if (turnFetches === 1) {
+ return Promise.reject(new TypeError("network down"));
+ }
+ return retryPage;
+ });
+ vi.stubGlobal("fetch", fetchMock);
+ renderTurnsHarness("session-1");
+ await waitFor(() => expect(currentTurnsState?.error?.retryable).toBe(true));
+
+ // Retry starts a fresh page that is still in flight when live events land.
+ act(() => currentTurnsState?.retry());
+ await waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2));
+
+ act(() => {
+ transport.listener?.(
+ event(1, "session.turn.started", {
+ id: "turn-1",
+ started_at: MESSAGE_CREATED_AT,
+ completed_at: null,
+ created_at: MESSAGE_CREATED_AT,
+ updated_at: MESSAGE_CREATED_AT,
+ }),
+ );
+ transport.listener?.(
+ event(2, "session.turn.completed", {
+ id: "turn-1",
+ started_at: MESSAGE_CREATED_AT,
+ completed_at: MESSAGE_CREATED_AT,
+ created_at: MESSAGE_CREATED_AT,
+ updated_at: MESSAGE_CREATED_AT,
+ }),
+ );
+ });
+
+ await act(async () => {
+ resolveRetry?.(response({ turns: [], hasMore: false, cursor: null }));
+ await Promise.resolve();
+ });
+ // The buffered live events drain on top of the (empty) retry page instead
+ // of being lost, and the completion survives the page assignment.
+ await waitFor(() =>
+ expect(currentTurnsState?.turns.find((turn) => turn.id === "turn-1")?.completedAt).toBe(
+ MESSAGE_CREATED_AT,
+ ),
+ );
+ });
+});
diff --git a/apps/web/lib/plugins/conversation-host.tsx b/apps/web/lib/plugins/conversation-host.tsx
new file mode 100644
index 0000000000..0dbbe8dcbe
--- /dev/null
+++ b/apps/web/lib/plugins/conversation-host.tsx
@@ -0,0 +1,896 @@
+/* eslint-disable max-lines -- The facade hook centralizes ordered snapshot/live state coordination. */
+"use client";
+
+import * as React from "react";
+import { useMessageFavoritesStore } from "@/lib/state/slices/message-favorites";
+import {
+ compareConversationMessages,
+ eventMatchesTask,
+ eventString,
+ messageFromEvent,
+ turnFromEvent,
+} from "./conversation-event-projection";
+import type {
+ PluginConversationApi,
+ PluginConversationError,
+ PluginConversationMessage,
+ PluginConversationTurn,
+ PluginSessionMessagesQuery,
+ PluginSessionMessagesState,
+ PluginSessionTurnsState,
+} from "./types";
+import {
+ ConversationScopeContext,
+ parseConversationResponse,
+ pluginConversationUrl,
+ type ConversationScope,
+} from "./conversation-scope";
+export { PluginConversationScopeProvider } from "./conversation-scope";
+
+type MessagePage = {
+ messages: PluginConversationMessage[];
+ hasMore: boolean;
+ cursor: string | null;
+};
+
+type TurnsPage = { turns: PluginConversationTurn[] };
+
+const EMPTY_MESSAGES: PluginSessionMessagesState = {
+ messages: [],
+ loading: false,
+ hydrated: false,
+ loadingMore: false,
+ error: null,
+ hasMore: false,
+ removed: false,
+ loadMore: async () => 0,
+ retry: () => undefined,
+};
+
+const EMPTY_TURNS: PluginSessionTurnsState = {
+ turns: [],
+ loading: false,
+ hydrated: false,
+ error: null,
+ removed: false,
+ retry: () => undefined,
+};
+
+function conversationError(error: unknown): PluginConversationError {
+ if (typeof error === "object" && error !== null && "code" in error) {
+ return error as PluginConversationError;
+ }
+ return {
+ code: "upstream_failure",
+ // i18n-exempt: plugin-facing transport diagnostic; plugins render their own localized error UI.
+ message: error instanceof Error ? error.message : "Conversation request failed",
+ retryable: true,
+ };
+}
+
+function isRemovedConversationError(error: PluginConversationError): boolean {
+ return error.code === "not_found";
+}
+
+function resolveTaskId(
+ scope: ConversationScope,
+ taskId: string | null | undefined,
+): { taskId: string | null; error: PluginConversationError | null } {
+ const resolved = taskId === undefined ? scope.taskId : taskId;
+ if (resolved === "" || (typeof resolved === "string" && resolved !== scope.taskId)) {
+ return {
+ taskId: null,
+ error: {
+ code: "invalid_query",
+ // i18n-exempt: plugin-facing programmer diagnostic; plugins render their own localized error UI.
+ message: "taskId must match the active task",
+ retryable: false,
+ },
+ };
+ }
+ return { taskId: resolved, error: null };
+}
+
+type MessagesState = Omit;
+type MessagesSetter = React.Dispatch>;
+
+// Session deletion emits child tombstones before its terminal marker. Keep
+// rows removed by that ordered teardown so the terminal view can retain the
+// committed conversation state.
+function restoreDeletedMessages(
+ current: readonly PluginConversationMessage[],
+ deleted: ReadonlyMap,
+ sort: "asc" | "desc",
+): PluginConversationMessage[] {
+ const messages = [...current];
+ const currentIds = new Set(messages.map((message) => message.id));
+ for (const message of deleted.values()) {
+ if (currentIds.has(message.id)) continue;
+ messages.push(message);
+ }
+ messages.sort((left, right) => compareConversationMessages(left, right, sort));
+ return messages;
+}
+
+function useOrderedMessageEvents({
+ scope,
+ sessionId,
+ taskId,
+ authorsKey,
+ sort,
+ snapshotKey,
+ setState,
+ cursorRef,
+ messagesRef,
+ deletedMessagesRef,
+}: {
+ scope: ConversationScope | null;
+ sessionId: string | null;
+ taskId: string | null;
+ authorsKey: string;
+ sort: "asc" | "desc";
+ snapshotKey: string;
+ setState: MessagesSetter;
+ cursorRef: React.MutableRefObject;
+ messagesRef: React.MutableRefObject;
+ deletedMessagesRef: React.MutableRefObject>;
+}) {
+ React.useEffect(() => {
+ if (!scope || !sessionId) return;
+ const allowedAuthorTypes = authorsKey ? new Set(authorsKey.split(",")) : null;
+ return scope.subscribe(
+ (event) => {
+ if (event.event_type === "session.removed") {
+ setState((current) => {
+ const messages = restoreDeletedMessages(
+ current.messages,
+ deletedMessagesRef.current,
+ sort,
+ );
+ messagesRef.current = messages;
+ return { ...current, messages, removed: true, hasMore: false, loading: false };
+ });
+ cursorRef.current = null;
+ return true;
+ }
+ if (!event.event_type.startsWith("message.") || !eventMatchesTask(event, taskId)) {
+ return true;
+ }
+ const messageId = eventString(event, "message_id");
+ if (!messageId) return false;
+ if (event.event_type === "message.deleted") {
+ setState((current) => {
+ const deleted = current.messages.find((message) => message.id === messageId);
+ if (deleted) deletedMessagesRef.current.set(messageId, deleted);
+ const messages = current.messages.filter((message) => message.id !== messageId);
+ messagesRef.current = messages;
+ return { ...current, messages };
+ });
+ return true;
+ }
+ const message = messageFromEvent(event);
+ if (!message) return false;
+ if (allowedAuthorTypes && !allowedAuthorTypes.has(message.authorType)) return true;
+ deletedMessagesRef.current.delete(message.id);
+ setState((current) => {
+ const messages = current.messages.filter((item) => item.id !== message.id);
+ messages.push(message);
+ messages.sort((left, right) => compareConversationMessages(left, right, sort));
+ messagesRef.current = messages;
+ return { ...current, messages };
+ });
+ return true;
+ },
+ "messages",
+ snapshotKey,
+ );
+ }, [
+ authorsKey,
+ cursorRef,
+ deletedMessagesRef,
+ messagesRef,
+ scope,
+ sessionId,
+ setState,
+ snapshotKey,
+ sort,
+ taskId,
+ ]);
+}
+
+function useInitialMessagePage({
+ scope,
+ sessionId,
+ error,
+ revision,
+ loadPage,
+ setState,
+ cursorRef,
+ loadMoreRef,
+ messagesRef,
+ deletedMessagesRef,
+ requestRevisionRef,
+ snapshotKey,
+}: {
+ scope: ConversationScope | null;
+ sessionId: string | null;
+ error: PluginConversationError | null;
+ revision: number;
+ loadPage: (cursor: string | null, append: boolean) => Promise;
+ setState: MessagesSetter;
+ cursorRef: React.MutableRefObject;
+ loadMoreRef: React.MutableRefObject | null>;
+ messagesRef: React.MutableRefObject;
+ deletedMessagesRef: React.MutableRefObject>;
+ requestRevisionRef: React.MutableRefObject;
+ snapshotKey: string;
+}) {
+ React.useEffect(() => {
+ requestRevisionRef.current += 1;
+ cursorRef.current = null;
+ loadMoreRef.current = null;
+ messagesRef.current = [];
+ deletedMessagesRef.current.clear();
+ if (!scope || !sessionId) {
+ setState({ ...EMPTY_MESSAGES, messages: [] });
+ return;
+ }
+ if (error) {
+ setState({ ...EMPTY_MESSAGES, messages: [], error });
+ return;
+ }
+ setState({ ...EMPTY_MESSAGES, messages: [] });
+ void loadPage(null, false).catch((cause: unknown) => {
+ if (scope.signal.aborted || scope.isTerminal()) return;
+ const error = conversationError(cause);
+ if (isRemovedConversationError(error)) {
+ setState((current) => ({
+ ...current,
+ loading: false,
+ loadingMore: false,
+ error: null,
+ hasMore: false,
+ removed: true,
+ }));
+ return;
+ }
+ setState({ ...EMPTY_MESSAGES, messages: [], error });
+ });
+ }, [
+ cursorRef,
+ deletedMessagesRef,
+ error,
+ loadMoreRef,
+ loadPage,
+ messagesRef,
+ requestRevisionRef,
+ revision,
+ scope,
+ sessionId,
+ setState,
+ snapshotKey,
+ ]);
+}
+function invalidateFreshMessagesSnapshot(scope: ConversationScope, snapshotKey: string): void {
+ scope.invalidateSnapshot("messages", snapshotKey);
+}
+
+function isScopeRequestable(scope: ConversationScope): boolean {
+ return !scope.signal.aborted && !scope.isTerminal();
+}
+
+function canLoadMore(
+ scope: ConversationScope | null,
+ sessionId: string | null,
+ state: { removed: boolean; hasMore: boolean },
+ cursor: string | null,
+): boolean {
+ return Boolean(
+ scope && sessionId && isScopeRequestable(scope) && !state.removed && state.hasMore && cursor,
+ );
+}
+
+type MessagePageLoaderOptions = {
+ scope: ConversationScope | null;
+ sessionId: string | null;
+ taskId: string | null;
+ error: PluginConversationError | null;
+ authorsKey: string;
+ sort: "asc" | "desc";
+ limit: number;
+ snapshotKey: string;
+ setState: MessagesSetter;
+ cursorRef: React.MutableRefObject;
+ messagesRef: React.MutableRefObject;
+ requestRevisionRef: React.MutableRefObject;
+};
+
+async function fetchMessagePage({
+ scope,
+ sessionId,
+ taskId,
+ authorsKey,
+ sort,
+ limit,
+ cursor,
+ binding,
+}: {
+ scope: ConversationScope;
+ sessionId: string;
+ taskId: string | null;
+ authorsKey: string;
+ sort: "asc" | "desc";
+ limit: number;
+ cursor: string | null;
+ binding: { bindingToken: string; snapshotToken: string };
+}): Promise {
+ const params = new URLSearchParams({ sort, limit: String(limit) });
+ if (taskId !== null) params.set("task_id", taskId);
+ for (const author of authorsKey ? authorsKey.split(",") : []) {
+ params.append("author_type", author);
+ }
+ if (cursor) params.set("cursor", cursor);
+ const response = await fetch(
+ pluginConversationUrl(
+ scope.pluginId,
+ `/conversation/task-sessions/${encodeURIComponent(sessionId)}/messages?${params}`,
+ ),
+ {
+ credentials: "include",
+ cache: "no-store",
+ headers: {
+ "X-Kandev-Plugin-Binding": binding.bindingToken,
+ "X-Kandev-Snapshot-Token": binding.snapshotToken,
+ },
+ signal: scope.signal,
+ },
+ );
+ return parseConversationResponse(response);
+}
+
+function mergeMessagePage(
+ current: readonly PluginConversationMessage[],
+ page: readonly PluginConversationMessage[],
+ append: boolean,
+ sort: "asc" | "desc",
+): { messages: PluginConversationMessage[]; additionCount: number } {
+ const existingIds = new Set(current.map((message) => message.id));
+ const messagesById = new Map();
+ if (append) {
+ for (const message of current) messagesById.set(message.id, message);
+ }
+ for (const message of page) {
+ const previous = messagesById.get(message.id);
+ if (!previous || previous.updatedAt.localeCompare(message.updatedAt) < 0) {
+ messagesById.set(message.id, message);
+ }
+ }
+ const messages = Array.from(messagesById.values());
+ messages.sort((left, right) => compareConversationMessages(left, right, sort));
+ return {
+ messages,
+ additionCount: page.filter((message) => !existingIds.has(message.id)).length,
+ };
+}
+
+function useMessagePageLoader({
+ scope,
+ sessionId,
+ taskId,
+ error,
+ authorsKey,
+ sort,
+ limit,
+ snapshotKey,
+ setState,
+ cursorRef,
+ messagesRef,
+ requestRevisionRef,
+}: MessagePageLoaderOptions) {
+ return React.useCallback(
+ async (cursor: string | null, append: boolean): Promise => {
+ if (!scope || !sessionId || !isScopeRequestable(scope)) return 0;
+ if (error) throw error;
+ // A fresh full page or continuation must not let a concurrent live
+ // update project and then be overwritten by the stale page response.
+ // Continuations also invalidate their committed snapshot so deletions
+ // cannot be acknowledged while the page is in flight and resurrected
+ invalidateFreshMessagesSnapshot(scope, snapshotKey);
+ const continuationSnapshotInvalidated = append;
+ try {
+ let capturedRevision = requestRevisionRef.current;
+ let binding = await scope.ready();
+ let pageCursor = cursor;
+ if (pageCursor) {
+ const renewal = await scope.renewContinuation(pageCursor, snapshotKey);
+ if (renewal.recovered) {
+ capturedRevision = requestRevisionRef.current;
+ pageCursor = cursorRef.current;
+ if (!pageCursor) return 0;
+ } else {
+ pageCursor = renewal.cursor;
+ }
+ binding = renewal.binding;
+ }
+ const page = await fetchMessagePage({
+ scope,
+ sessionId,
+ taskId,
+ authorsKey,
+ sort,
+ limit,
+ cursor: pageCursor,
+ binding,
+ });
+ if (
+ requestRevisionRef.current !== capturedRevision ||
+ scope.signal.aborted ||
+ scope.isTerminal()
+ ) {
+ if (continuationSnapshotInvalidated) scope.commitSnapshot("messages", snapshotKey);
+ return 0;
+ }
+ const { messages, additionCount } = mergeMessagePage(
+ messagesRef.current,
+ page.messages,
+ append,
+ sort,
+ );
+ messagesRef.current = messages;
+ setState((current) => ({
+ ...current,
+ messages,
+ loading: false,
+ hydrated: true,
+ loadingMore: false,
+ error: null,
+ hasMore: page.hasMore,
+ }));
+ scope.commitSnapshot("messages", snapshotKey);
+ cursorRef.current = page.cursor;
+ return additionCount;
+ } catch (cause) {
+ if (continuationSnapshotInvalidated) scope.commitSnapshot("messages", snapshotKey);
+ throw cause;
+ }
+ },
+ [
+ authorsKey,
+ error,
+ limit,
+ messagesRef,
+ requestRevisionRef,
+ scope,
+ snapshotKey,
+ sessionId,
+ setState,
+ sort,
+ taskId,
+ ],
+ );
+}
+
+function useMessageRebind({
+ scope,
+ sessionId,
+ error,
+ loadPage,
+ setState,
+ cursorRef,
+ deletedMessagesRef,
+ requestRevisionRef,
+}: {
+ scope: ConversationScope | null;
+ sessionId: string | null;
+ error: PluginConversationError | null;
+ loadPage: (cursor: string | null, append: boolean) => Promise;
+ setState: MessagesSetter;
+ cursorRef: React.MutableRefObject;
+ deletedMessagesRef: React.MutableRefObject>;
+ requestRevisionRef: React.MutableRefObject;
+}) {
+ React.useEffect(() => {
+ if (!scope || !sessionId || error) return;
+ return scope.subscribeRebind(async () => {
+ requestRevisionRef.current += 1;
+ cursorRef.current = null;
+ deletedMessagesRef.current.clear();
+ setState((current) => ({ ...current, loading: true, loadingMore: false, error: null }));
+ try {
+ await loadPage(null, false);
+ } catch (cause) {
+ if (scope.signal.aborted || scope.isTerminal()) return;
+ setState((current) => ({
+ ...current,
+ loading: false,
+ error: conversationError(cause),
+ }));
+ throw cause;
+ }
+ });
+ }, [
+ cursorRef,
+ deletedMessagesRef,
+ error,
+ loadPage,
+ requestRevisionRef,
+ scope,
+ sessionId,
+ setState,
+ ]);
+}
+
+function useMessageControls({
+ scope,
+ sessionId,
+ state,
+ setState,
+ loadPage,
+ cursorRef,
+ loadMoreRef,
+ setRevision,
+}: {
+ scope: ConversationScope | null;
+ sessionId: string | null;
+ state: MessagesState;
+ setState: MessagesSetter;
+ loadPage: (cursor: string | null, append: boolean) => Promise;
+ cursorRef: React.MutableRefObject;
+ loadMoreRef: React.MutableRefObject | null>;
+ setRevision: React.Dispatch>;
+}): PluginSessionMessagesState {
+ const loadMore = React.useCallback((): Promise => {
+ if (!canLoadMore(scope, sessionId, state, cursorRef.current)) return Promise.resolve(0);
+ if (loadMoreRef.current) return loadMoreRef.current;
+ setState((current) => ({ ...current, loadingMore: true }));
+ const request = loadPage(cursorRef.current, true)
+ .catch((error: unknown) => {
+ setState((current) => ({
+ ...current,
+ loadingMore: false,
+ error: conversationError(error),
+ }));
+ throw conversationError(error);
+ })
+ .finally(() => {
+ if (loadMoreRef.current === request) loadMoreRef.current = null;
+ });
+ loadMoreRef.current = request;
+ return request;
+ }, [cursorRef, loadMoreRef, loadPage, scope, sessionId, setState, state.hasMore, state.removed]);
+
+ const retry = React.useCallback(() => {
+ if (!state.error?.retryable || state.removed || !scope || scope.isTerminal() || !sessionId)
+ return;
+ setRevision((value) => value + 1);
+ }, [scope, sessionId, setRevision, state.error, state.removed]);
+
+ return React.useMemo(() => ({ ...state, loadMore, retry }), [loadMore, retry, state]);
+}
+
+function useSessionMessages(query: PluginSessionMessagesQuery): PluginSessionMessagesState {
+ const scope = React.useContext(ConversationScopeContext);
+ const [revision, setRevision] = React.useState(0);
+ const [state, setState] = React.useState>({
+ ...EMPTY_MESSAGES,
+ });
+ const cursorRef = React.useRef(null);
+ const loadMoreRef = React.useRef | null>(null);
+ const messagesRef = React.useRef([]);
+ const deletedMessagesRef = React.useRef(new Map());
+ const requestRevisionRef = React.useRef(0);
+ const resolved = React.useMemo(
+ () => (scope ? resolveTaskId(scope, query.taskId) : { taskId: null, error: null }),
+ [query.taskId, scope],
+ );
+ const authorsKey = [...(query.authorTypes ?? [])].join(",");
+ const sort = query.sort ?? "desc";
+ const limit = query.pageSize ?? 20;
+ const snapshotKey = JSON.stringify([query.sessionId, resolved.taskId, authorsKey, sort, limit]);
+
+ const loadPage = useMessagePageLoader({
+ scope,
+ sessionId: query.sessionId,
+ taskId: resolved.taskId,
+ error: resolved.error,
+ authorsKey,
+ sort,
+ limit,
+ snapshotKey,
+ setState,
+ cursorRef,
+ messagesRef,
+ requestRevisionRef,
+ });
+ useOrderedMessageEvents({
+ scope: resolved.error ? null : scope,
+ sessionId: query.sessionId,
+ taskId: resolved.taskId,
+ authorsKey,
+ sort,
+ snapshotKey,
+ setState,
+ cursorRef,
+ messagesRef,
+ deletedMessagesRef,
+ });
+
+ useInitialMessagePage({
+ scope,
+ sessionId: query.sessionId,
+ error: resolved.error,
+ revision,
+ loadPage,
+ setState,
+ cursorRef,
+ loadMoreRef,
+ messagesRef,
+ deletedMessagesRef,
+ requestRevisionRef,
+ snapshotKey,
+ });
+
+ useMessageRebind({
+ scope,
+ sessionId: query.sessionId,
+ error: resolved.error,
+ loadPage,
+ setState,
+ cursorRef,
+ deletedMessagesRef,
+ requestRevisionRef,
+ });
+ return useMessageControls({
+ scope,
+ sessionId: query.sessionId,
+ state,
+ setState,
+ loadPage,
+ cursorRef,
+ loadMoreRef,
+ setRevision,
+ });
+}
+
+type TurnsState = Omit;
+type TurnsSetter = React.Dispatch>;
+
+function compareConversationTurns(
+ left: PluginConversationTurn,
+ right: PluginConversationTurn,
+): number {
+ const started = left.startedAt.localeCompare(right.startedAt);
+ return started === 0 ? left.id.localeCompare(right.id) : started;
+}
+
+function restoreDeletedTurns(
+ current: readonly PluginConversationTurn[],
+ deleted: ReadonlyMap,
+): PluginConversationTurn[] {
+ const turns = [...current];
+ const currentIds = new Set(turns.map((turn) => turn.id));
+ for (const turn of deleted.values()) {
+ if (currentIds.has(turn.id)) continue;
+ turns.push(turn);
+ }
+ turns.sort(compareConversationTurns);
+ return turns;
+}
+
+function useOrderedTurnEvents({
+ scope,
+ sessionId,
+ taskId,
+ error,
+ snapshotKey,
+ setState,
+ deletedTurnsRef,
+}: {
+ scope: ConversationScope | null;
+ sessionId: string | null;
+ taskId: string | null;
+ error: PluginConversationError | null;
+ snapshotKey: string;
+ setState: TurnsSetter;
+ deletedTurnsRef: React.MutableRefObject>;
+}) {
+ React.useEffect(() => {
+ if (!scope || !sessionId || error) return;
+ return scope.subscribe(
+ (event) => {
+ if (event.event_type === "session.removed") {
+ setState((current) => ({
+ ...current,
+ turns: restoreDeletedTurns(current.turns, deletedTurnsRef.current),
+ removed: true,
+ loading: false,
+ }));
+ return true;
+ }
+ if (!eventMatchesTask(event, taskId)) return true;
+ if (event.event_type === "session.turn.removed") {
+ const payload = event.payload;
+ const turnId =
+ payload &&
+ typeof payload === "object" &&
+ "id" in payload &&
+ typeof payload.id === "string"
+ ? payload.id
+ : undefined;
+ if (!turnId) return false;
+ setState((current) => {
+ const deleted = current.turns.find((turn) => turn.id === turnId);
+ if (deleted) deletedTurnsRef.current.set(turnId, deleted);
+ return {
+ ...current,
+ turns: current.turns.filter((item) => item.id !== turnId),
+ };
+ });
+ return true;
+ }
+ if (!event.event_type.startsWith("session.turn.")) return true;
+ const turn = turnFromEvent(event);
+ if (!turn) return false;
+ deletedTurnsRef.current.delete(turn.id);
+ setState((current) => {
+ const turns = current.turns.filter((item) => item.id !== turn.id);
+ turns.push(turn);
+ turns.sort(compareConversationTurns);
+ return { ...current, turns, hydrated: true };
+ });
+ return true;
+ },
+ "turns",
+ snapshotKey,
+ );
+ }, [deletedTurnsRef, error, scope, sessionId, setState, snapshotKey, taskId]);
+}
+// eslint-disable-next-line max-lines-per-function -- keeps turn snapshot lifecycle in one hook.
+function useSessionTurns(
+ sessionId: string | null,
+ taskId?: string | null,
+): PluginSessionTurnsState {
+ const scope = React.useContext(ConversationScopeContext);
+ const [revision, setRevision] = React.useState(0);
+ const [state, setState] = React.useState>({
+ ...EMPTY_TURNS,
+ turns: [],
+ });
+ const resolved = React.useMemo(
+ () => (scope ? resolveTaskId(scope, taskId) : { taskId: null, error: null }),
+ [scope, taskId],
+ );
+ const snapshotKey = JSON.stringify([sessionId, resolved.taskId]);
+ const turnsRequestRef = React.useRef(0);
+ const deletedTurnsRef = React.useRef(new Map());
+
+ useOrderedTurnEvents({
+ scope,
+ sessionId,
+ taskId: resolved.taskId,
+ error: resolved.error,
+ snapshotKey,
+ setState,
+ deletedTurnsRef,
+ });
+
+ const loadTurns = React.useCallback(async (): Promise => {
+ deletedTurnsRef.current.clear();
+ if (!scope || !sessionId) {
+ setState({ ...EMPTY_TURNS, turns: [] });
+ return;
+ }
+ if (resolved.error) {
+ setState({ ...EMPTY_TURNS, turns: [], error: resolved.error });
+ return;
+ }
+ const requestId = ++turnsRequestRef.current;
+ // A fresh turns page (initial load, retry, or binding refresh) must not
+ // let a concurrent live turn event project and then be overwritten by the
+ // stale page response: buffer live events until the new snapshot commits,
+ // then drain them on top.
+ scope.invalidateSnapshot("turns", snapshotKey);
+ setState((previous) =>
+ revision === 0
+ ? { ...EMPTY_TURNS, turns: [], loading: true }
+ : { ...previous, loading: true, error: null },
+ );
+ try {
+ const binding = await scope.ready();
+ const params = new URLSearchParams();
+ if (resolved.taskId !== null) params.set("task_id", resolved.taskId);
+ const queryString = params.size ? `?${params}` : "";
+ const response = await fetch(
+ pluginConversationUrl(
+ scope.pluginId,
+ `/conversation/task-sessions/${encodeURIComponent(sessionId)}/turns${queryString}`,
+ ),
+ {
+ credentials: "include",
+ cache: "no-store",
+ headers: {
+ "X-Kandev-Plugin-Binding": binding.bindingToken,
+ "X-Kandev-Snapshot-Token": binding.snapshotToken,
+ },
+ signal: scope.signal,
+ },
+ );
+ const page = await parseConversationResponse(response);
+ if (turnsRequestRef.current !== requestId || scope.signal.aborted || scope.isTerminal()) {
+ return;
+ }
+ setState((previous) => ({
+ ...previous,
+ turns: page.turns,
+ loading: false,
+ hydrated: true,
+ error: null,
+ }));
+ scope.commitSnapshot("turns", snapshotKey);
+ } catch (cause) {
+ if (turnsRequestRef.current !== requestId || scope.signal.aborted || scope.isTerminal()) {
+ return;
+ }
+ const error = conversationError(cause);
+ if (isRemovedConversationError(error)) {
+ setState((previous) => ({
+ ...previous,
+ loading: false,
+ error: null,
+ removed: true,
+ }));
+ return;
+ }
+ setState((previous) => ({
+ ...(revision === 0 ? { ...EMPTY_TURNS, turns: [] } : previous),
+ loading: false,
+ error,
+ }));
+ throw cause;
+ }
+ }, [
+ deletedTurnsRef,
+ resolved.error,
+ resolved.taskId,
+ revision,
+ scope,
+ sessionId,
+ setState,
+ snapshotKey,
+ ]);
+
+ React.useEffect(() => {
+ void loadTurns().catch(() => {});
+ return () => {
+ turnsRequestRef.current += 1;
+ };
+ }, [loadTurns]);
+
+ React.useEffect(() => {
+ if (!scope || !sessionId || resolved.error) return;
+ return scope.subscribeRebind(() => loadTurns());
+ }, [loadTurns, resolved.error, scope, sessionId]);
+
+ const retry = React.useCallback(() => {
+ if (!state.error?.retryable || state.removed || !scope || !sessionId) return;
+ setRevision((value) => value + 1);
+ }, [scope, sessionId, state.error, state.removed]);
+
+ return React.useMemo(() => ({ ...state, retry }), [retry, state]);
+}
+
+function useMessageFavorite(sessionId: string | null, messageId: string): boolean {
+ const hydrateSession = useMessageFavoritesStore((state) => state.hydrateSession);
+ React.useEffect(() => {
+ if (sessionId) hydrateSession(sessionId);
+ }, [hydrateSession, sessionId]);
+ return useMessageFavoritesStore((state) =>
+ sessionId ? Boolean(state.bySession[sessionId]?.[messageId]) : false,
+ );
+}
+
+export const pluginConversationApi: PluginConversationApi = {
+ useSessionMessages,
+ useSessionTurns,
+ useMessageFavorite,
+};
diff --git a/apps/web/lib/plugins/conversation-scope.tsx b/apps/web/lib/plugins/conversation-scope.tsx
new file mode 100644
index 0000000000..7e0b2e78ae
--- /dev/null
+++ b/apps/web/lib/plugins/conversation-scope.tsx
@@ -0,0 +1,780 @@
+/* eslint-disable max-lines -- The scope owns transport, ordering, and snapshot lifecycle state. */
+"use client";
+
+import * as React from "react";
+import { getBackendConfig } from "@/lib/config";
+import { parseTurnTimestamp } from "@/lib/state/slices/session/turn-actions";
+import { generateUUID } from "@/lib/uuid";
+import { isRawSessionEvent } from "@/lib/ws/ordered-session-events";
+import { getWebSocketClient } from "@/lib/ws/connection";
+import type { RawSessionEvent } from "@/lib/ws/client";
+import type { PluginConversationError } from "./types";
+
+export type OrderedReady = {
+ bindingToken: string;
+ generation: number;
+ expiresAt: string;
+ snapshotExpiresAt: string;
+ snapshotToken: string;
+ resumeToken: string;
+ consumerId: string;
+ watermark: number;
+};
+
+type Binding = Pick;
+type SnapshotKind = "messages" | "turns";
+type ConversationEventListener = (event: RawSessionEvent) => boolean;
+type SnapshotKey = string;
+type OrderedSubscribeAck =
+ | {
+ success: true;
+ snapshot_token: string;
+ resume_token: string;
+ consumer_id: string;
+ event_watermark: number;
+ expires_at: string;
+ result: "fresh" | "replay" | "invalid_resume";
+ replay_from?: number;
+ }
+ | {
+ success: false;
+ error:
+ | PluginConversationError
+ | { code: "session_removed"; message: string; retryable: false };
+ };
+type ContinuationRenewal = {
+ cursor: string;
+ snapshot_token: string;
+ expires_at: string;
+};
+type ErrorEnvelope = { error?: PluginConversationError };
+type RebindListener = () => void | Promise;
+type ContinuationResult = { cursor: string; binding: OrderedReady; recovered?: boolean };
+
+export type ConversationScope = {
+ pluginId: string;
+ taskId: string;
+ sessionId: string | null;
+ signal: AbortSignal;
+ ready(): Promise;
+ renewContinuation(cursor: string, queryIdentity?: string): Promise;
+ subscribe(
+ listener: ConversationEventListener,
+ kind: SnapshotKind,
+ snapshotKey: SnapshotKey,
+ ): () => void;
+ subscribeRebind(listener: RebindListener): () => void;
+ isTerminal(): boolean;
+ commitSnapshot(kind: SnapshotKind, snapshotKey?: SnapshotKey): void;
+ invalidateSnapshot(kind: SnapshotKind, snapshotKey?: SnapshotKey): void;
+ reconnect(): void;
+ accept(event: RawSessionEvent): void;
+ close(): void;
+};
+
+export const ConversationScopeContext = React.createContext(null);
+
+export function pluginConversationUrl(pluginId: string, path: string): string {
+ const { apiBaseUrl } = getBackendConfig();
+ return `${apiBaseUrl}/api/plugins/${encodeURIComponent(pluginId)}${path}`;
+}
+
+export async function parseConversationResponse(response: Response): Promise {
+ if (response.ok) return (await response.json()) as T;
+ const body = (await response.json().catch(() => ({}))) as ErrorEnvelope;
+ throw (
+ body.error ?? {
+ code: "upstream_failure",
+ // i18n-exempt: plugin-facing transport diagnostic; plugins render their own localized error UI.
+ message: `Conversation request failed with status ${response.status}`,
+ retryable: response.status >= 500,
+ }
+ );
+}
+
+async function fetchBinding(pluginId: string, signal: AbortSignal): Promise {
+ const response = await fetch(pluginConversationUrl(pluginId, "/conversation/binding"), {
+ credentials: "include",
+ cache: "no-store",
+ signal,
+ });
+ return parseConversationResponse(response);
+}
+
+const SESSION_REMOVED_EVENT = "session.removed";
+const SESSION_SUBSCRIBE_ACTION = "session.subscribe";
+
+const ORDERED_EVENT_TYPES: Record = {
+ "message.added": true,
+ "message.updated": true,
+ "message.deleted": true,
+ "session.turn.started": true,
+ "session.turn.completed": true,
+ "session.turn.removed": true,
+ [SESSION_REMOVED_EVENT]: true,
+};
+
+function isNonEmptyPayloadString(payload: Record, key: string): boolean {
+ return typeof payload[key] === "string" && (payload[key] as string).length > 0;
+}
+
+function isValidPayloadTime(payload: Record, key: string): boolean {
+ if (!isNonEmptyPayloadString(payload, key)) return false;
+ const value = payload[key];
+ return typeof value === "string" && parseTurnTimestamp(value) !== null;
+}
+
+function isValidMessagePayload(payload: Record, updated: boolean): boolean {
+ return (
+ isNonEmptyPayloadString(payload, "message_id") &&
+ (payload.author_type === "user" || payload.author_type === "agent") &&
+ typeof payload.content === "string" &&
+ isValidPayloadTime(payload, "created_at") &&
+ (!updated || isValidPayloadTime(payload, "updated_at"))
+ );
+}
+
+function isValidTurnPayload(payload: Record, completed: boolean): boolean {
+ return (
+ isNonEmptyPayloadString(payload, "id") &&
+ isValidPayloadTime(payload, "started_at") &&
+ (!completed ||
+ (isValidPayloadTime(payload, "completed_at") && isValidPayloadTime(payload, "updated_at")))
+ );
+}
+// eventPayloadValidators mirrors backend ProjectSessionEvent's per-event
+// required-field checks. session.removed is intentionally absent: a removal is
+// accepted for the selected session regardless of its task_id.
+const eventPayloadValidators: Record) => boolean> = {
+ "message.added": (payload) => isValidMessagePayload(payload, false),
+ "message.updated": (payload) => isValidMessagePayload(payload, true),
+ "message.deleted": (payload) => isNonEmptyPayloadString(payload, "message_id"),
+ "session.turn.started": (payload) => isValidTurnPayload(payload, false),
+ "session.turn.completed": (payload) => isValidTurnPayload(payload, true),
+ "session.turn.removed": (payload) => isNonEmptyPayloadString(payload, "id"),
+};
+
+function isCompatibleConversationEvent(event: RawSessionEvent, sessionId: string): boolean {
+ if (!isRawSessionEvent(event) || event.session_id !== sessionId) return false;
+ if (
+ !(event.event_type in ORDERED_EVENT_TYPES) ||
+ !event.payload ||
+ typeof event.payload !== "object"
+ ) {
+ return false;
+ }
+ const payload = event.payload as Record;
+ if (payload.type !== event.event_type || payload.session_id !== sessionId) return false;
+ if (event.event_type === SESSION_REMOVED_EVENT) {
+ return true;
+ }
+ // Every non-removal event must match the session's task identity exactly.
+ if (event.task_id !== null && payload.task_id !== event.task_id) return false;
+ const validator = eventPayloadValidators[event.event_type];
+ return validator ? validator(payload) : false;
+}
+
+function snapshotKindForEvent(eventType: string): SnapshotKind | null {
+ if (eventType.startsWith("message.")) return "messages";
+ if (eventType.startsWith("session.turn.")) return "turns";
+ return null;
+}
+
+class OrderedConversationScope implements ConversationScope {
+ readonly signal: AbortSignal;
+ private bindingPromise: Promise | null = null;
+ private readyPromise: Promise | null = null;
+ private readonly renewalPromises = new Map>();
+ private bindingRefreshPromise: Promise | null = null;
+ private continuationRecoveryPromise: Promise | null = null;
+ private stateGeneration = 0;
+ private currentResumeToken = "";
+ private readonly committedSnapshots = new Set();
+ private acknowledgedSequence = 0;
+ private nextSequence = 1;
+ private sequenceBlocked = false;
+ private terminal = false;
+ private closed = false;
+ private ackChain = Promise.resolve();
+ private readonly listeners = new Set();
+ private readonly listenerSnapshotKeys = new Map();
+ private readonly listenerSnapshotKinds = new Map();
+ private readonly rebindListeners = new Set<() => void>();
+ private poisonRebindPromise: Promise | null = null;
+ private readonly buffered: RawSessionEvent[] = [];
+ private readonly pendingBySequence = new Map();
+ private consumerId = generateUUID();
+
+ constructor(
+ readonly pluginId: string,
+ readonly taskId: string,
+ readonly sessionId: string | null,
+ private readonly controller: AbortController,
+ ) {
+ this.signal = controller.signal;
+ }
+
+ ready(): Promise {
+ const pending = (this.readyPromise ??= this.initializeReady());
+ return pending
+ .then((current) => this.refreshBindingIfNeeded(current))
+ .catch((error: unknown) => {
+ if (this.readyPromise === pending) this.readyPromise = null;
+ throw error;
+ });
+ }
+
+ async renewContinuation(cursor: string, queryIdentity = ""): Promise {
+ const current = await this.ready();
+ const snapshotExpiresAt = new Date(current.snapshotExpiresAt).getTime();
+ if (snapshotExpiresAt - Date.now() > 2 * 60 * 1000) {
+ return { cursor, binding: current };
+ }
+ if (snapshotExpiresAt <= Date.now()) {
+ const binding = await this.recoverExpiredContinuation(current);
+ return { cursor, binding, recovered: true };
+ }
+ const renewalKey = JSON.stringify([queryIdentity, cursor]);
+ const existing = this.renewalPromises.get(renewalKey);
+ if (existing) return existing;
+ const capturedGeneration = this.stateGeneration;
+ const pending = fetch(
+ pluginConversationUrl(this.pluginId, "/conversation/continuation/renew"),
+ {
+ method: "POST",
+ credentials: "include",
+ cache: "no-store",
+ headers: {
+ "Content-Type": "application/json",
+ "X-Kandev-Plugin-Binding": current.bindingToken,
+ },
+ body: JSON.stringify({ cursor, snapshot_token: current.snapshotToken }),
+ signal: this.signal,
+ },
+ )
+ .then((response) => parseConversationResponse(response))
+ .then((renewed) => {
+ if (this.stateGeneration !== capturedGeneration) {
+ return this.ready().then((binding) => ({ cursor, binding, recovered: true }));
+ }
+ const next = {
+ ...current,
+ snapshotToken: renewed.snapshot_token,
+ snapshotExpiresAt: renewed.expires_at,
+ };
+ this.readyPromise = Promise.resolve(next);
+ return { cursor: renewed.cursor, binding: next };
+ })
+ .catch((cause: unknown) => {
+ if (snapshotExpiresAt <= Date.now()) {
+ return this.recoverExpiredContinuation(current).then((binding) => ({
+ cursor,
+ binding,
+ recovered: true,
+ }));
+ }
+ throw cause;
+ })
+ .finally(() => {
+ if (this.renewalPromises.get(renewalKey) === pending) {
+ this.renewalPromises.delete(renewalKey);
+ }
+ });
+ this.renewalPromises.set(renewalKey, pending);
+ return pending;
+ }
+
+ subscribe(listener: ConversationEventListener, kind: SnapshotKind, snapshotKey: SnapshotKey) {
+ this.listeners.add(listener);
+ this.listenerSnapshotKeys.set(listener, snapshotKey);
+ this.listenerSnapshotKinds.set(listener, kind);
+ return () => {
+ this.listeners.delete(listener);
+ this.listenerSnapshotKeys.delete(listener);
+ this.listenerSnapshotKinds.delete(listener);
+ this.drainBuffered();
+ };
+ }
+
+ subscribeRebind(listener: RebindListener) {
+ this.rebindListeners.add(listener);
+ return () => this.rebindListeners.delete(listener);
+ }
+ isTerminal() {
+ return this.terminal;
+ }
+
+ invalidateSnapshot(kind: SnapshotKind, snapshotKey = "") {
+ if (this.closed) return;
+ this.committedSnapshots.delete(`${kind}:${snapshotKey}`);
+ }
+
+ commitSnapshot(kind: SnapshotKind, snapshotKey = "") {
+ if (this.closed || this.terminal) return;
+ this.committedSnapshots.add(`${kind}:${snapshotKey}`);
+ this.drainBuffered();
+ }
+
+ private drainBuffered() {
+ const pending = this.buffered.splice(0).sort((left, right) => left.sequence - right.sequence);
+ for (let index = 0; index < pending.length; index += 1) {
+ const event = pending[index];
+ if (!event) continue;
+ if (this.terminal) return;
+ if (this.shouldBuffer(event)) {
+ this.buffered.push(...pending.slice(index));
+ return;
+ }
+ if (!this.project(event)) {
+ this.buffered.unshift(...pending.slice(index + 1));
+ this.blockForPoison();
+ return;
+ }
+ }
+ }
+
+ accept(event: RawSessionEvent) {
+ const sessionId = this.sessionId;
+ if (!sessionId || event.session_id !== sessionId) return;
+ if (!isRawSessionEvent(event)) {
+ this.blockForPoison();
+ return;
+ }
+ if (!this.acceptsScope(event, sessionId) || event.sequence < this.nextSequence) return;
+ if (this.sequenceBlocked && event.event_type === SESSION_REMOVED_EVENT) {
+ if (isCompatibleConversationEvent(event, sessionId)) this.project(event, false);
+ return;
+ }
+ const existing = this.pendingBySequence.get(event.sequence);
+ if (existing) {
+ if (existing.event_id !== event.event_id || existing.event_type !== event.event_type) {
+ this.blockForPoison();
+ }
+ return;
+ }
+ this.pendingBySequence.set(event.sequence, event);
+ this.drainPending(sessionId);
+ }
+
+ private acceptsScope(event: RawSessionEvent, sessionId: string) {
+ return !this.closed && !this.terminal && event.session_id === sessionId;
+ }
+
+ private drainPending(sessionId: string) {
+ while (!this.sequenceBlocked && !this.terminal) {
+ const event = this.pendingBySequence.get(this.nextSequence);
+ if (!event) return;
+ if (!isCompatibleConversationEvent(event, sessionId)) {
+ this.blockForPoison();
+ return;
+ }
+ this.pendingBySequence.delete(this.nextSequence);
+ this.nextSequence += 1;
+ if (event.event_type === SESSION_REMOVED_EVENT) {
+ if (!this.project(event)) this.sequenceBlocked = true;
+ return;
+ }
+ if (this.shouldBuffer(event)) {
+ this.buffered.push(event);
+ continue;
+ }
+ if (!this.project(event)) {
+ this.sequenceBlocked = true;
+ return;
+ }
+ }
+ }
+
+ private shouldBuffer(event: RawSessionEvent) {
+ if (this.listeners.size === 0) return true;
+ const eventKind = snapshotKindForEvent(event.event_type);
+ if (eventKind === null) return false;
+ for (const listener of this.listeners) {
+ if (this.listenerSnapshotKinds.get(listener) !== eventKind) continue;
+ const snapshotKey = this.listenerSnapshotKeys.get(listener) ?? "";
+ if (!this.committedSnapshots.has(`${eventKind}:${snapshotKey}`)) return true;
+ }
+ return false;
+ }
+
+ reconnect() {
+ if (this.closed || this.terminal || !this.sessionId || !this.readyPromise) return;
+ void this.resume().catch(() => undefined);
+ }
+
+ close() {
+ this.closed = true;
+ this.buffered.length = 0;
+ this.rebindListeners.clear();
+ this.listeners.clear();
+ this.listenerSnapshotKeys.clear();
+ this.listenerSnapshotKinds.clear();
+ this.pendingBySequence.clear();
+ if (!this.sessionId || !this.readyPromise) return;
+ void this.readyPromise
+ .then((ready) =>
+ getWebSocketClient()?.request("session.unsubscribe", {
+ session_id: this.sessionId,
+ consumer_kind: "plugin",
+ consumer_id: this.consumerId,
+ plugin_id: this.pluginId,
+ generation: ready.generation,
+ }),
+ )
+ .catch(() => undefined);
+ }
+
+ private getBinding() {
+ const pending = (this.bindingPromise ??= fetchBinding(this.pluginId, this.signal));
+ return pending.catch((error: unknown) => {
+ if (this.bindingPromise === pending) this.bindingPromise = null;
+ throw error;
+ });
+ }
+ private async initializeReady(): Promise {
+ const binding = await this.getBinding();
+ if (!this.sessionId) {
+ return {
+ ...binding,
+ snapshotToken: "",
+ snapshotExpiresAt: binding.expiresAt,
+ resumeToken: "",
+ consumerId: this.consumerId,
+ watermark: 0,
+ };
+ }
+ const client = getWebSocketClient();
+ if (!client) {
+ // i18n-exempt: plugin-facing transport diagnostic; plugins render their own localized error UI.
+ throw new Error("WebSocket unavailable");
+ }
+ const ack = await client.request(SESSION_SUBSCRIBE_ACTION, {
+ session_id: this.sessionId,
+ consumer_kind: "plugin",
+ consumer_id: this.consumerId,
+ plugin_id: this.pluginId,
+ generation: binding.generation,
+ binding_token: binding.bindingToken,
+ });
+ if (!ack.success) throw ack.error;
+ this.consumerId = ack.consumer_id;
+ this.currentResumeToken = ack.resume_token;
+ // The subscribe ACK's watermark is the last durable sequence the server
+ // already holds; live projection starts at watermark+1. Seeding the
+ // cursor here (not at 1) is what lets an existing non-empty session drain
+ // its first live event instead of parking it forever waiting for
+ // sequence 1.
+ this.acknowledgedSequence = ack.event_watermark;
+ this.nextSequence = ack.event_watermark + 1;
+ return {
+ ...binding,
+ snapshotToken: ack.snapshot_token,
+ snapshotExpiresAt: ack.expires_at || binding.expiresAt,
+ resumeToken: ack.resume_token,
+ consumerId: ack.consumer_id,
+ watermark: ack.event_watermark,
+ };
+ }
+
+ private refreshBindingIfNeeded(current: OrderedReady): Promise {
+ if (new Date(current.expiresAt).getTime() - Date.now() > 2 * 60 * 1000) {
+ return Promise.resolve(current);
+ }
+ if (this.bindingRefreshPromise) return this.bindingRefreshPromise;
+ this.bindingPromise = fetchBinding(this.pluginId, this.signal);
+ const pending = this.bindingPromise
+ .then(async (binding) => {
+ if (binding.generation !== current.generation) {
+ return this.rebindGeneration(current, binding);
+ }
+ const next = { ...current, ...binding };
+ this.readyPromise = Promise.resolve(next);
+ return next;
+ })
+ .finally(() => {
+ if (this.bindingRefreshPromise === pending) this.bindingRefreshPromise = null;
+ });
+ this.bindingRefreshPromise = pending;
+ return pending;
+ }
+
+ private project(event: RawSessionEvent, acknowledge = true): boolean {
+ let projected = true;
+ for (const listener of this.listeners) {
+ try {
+ projected = listener(event) && projected;
+ } catch {
+ projected = false;
+ }
+ }
+ if (!projected) return false;
+ if (event.event_type === SESSION_REMOVED_EVENT) this.terminal = true;
+ if (acknowledge) {
+ this.ackChain = this.ackChain
+ .then(() => this.acknowledge(event.sequence))
+ .catch(() => {
+ this.sequenceBlocked = true;
+ });
+ }
+ return true;
+ }
+
+ private async acknowledge(sequence: number) {
+ const ready = await this.ready();
+ const client = getWebSocketClient();
+ if (!client || this.closed || !this.sessionId) return;
+ const ack = await client.request<{ success: true; resume_token: string } | { success: false }>(
+ "session.ack",
+ {
+ session_id: this.sessionId,
+ consumer_kind: "plugin",
+ consumer_id: this.consumerId,
+ plugin_id: this.pluginId,
+ generation: ready.generation,
+ sequence,
+ resume_token: this.currentResumeToken,
+ },
+ );
+ if (!ack.success) {
+ this.sequenceBlocked = true;
+ return;
+ }
+ this.currentResumeToken = ack.resume_token;
+ this.acknowledgedSequence = sequence;
+ }
+
+ private async rebindGeneration(current: OrderedReady, binding: Binding): Promise {
+ return this.rebindSubscription(current, binding);
+ }
+
+ private recoverExpiredContinuation(current: OrderedReady): Promise {
+ if (this.continuationRecoveryPromise) return this.continuationRecoveryPromise;
+ const pending = this.rebindSubscription(current, current).finally(() => {
+ if (this.continuationRecoveryPromise === pending) {
+ this.continuationRecoveryPromise = null;
+ }
+ });
+ this.continuationRecoveryPromise = pending;
+ return pending;
+ }
+
+ private async rebindSubscription(current: OrderedReady, binding: Binding): Promise {
+ const client = getWebSocketClient();
+ if (!client || this.closed || this.terminal || !this.sessionId) {
+ const next = { ...current, ...binding };
+ this.readyPromise = Promise.resolve(next);
+ return next;
+ }
+ const previousConsumerId = this.consumerId;
+ this.consumerId = generateUUID();
+ const ack = await client.request(SESSION_SUBSCRIBE_ACTION, {
+ session_id: this.sessionId,
+ consumer_kind: "plugin",
+ consumer_id: this.consumerId,
+ plugin_id: this.pluginId,
+ generation: binding.generation,
+ binding_token: binding.bindingToken,
+ });
+ if (!ack.success) {
+ this.consumerId = previousConsumerId;
+ throw ack.error;
+ }
+ this.consumerId = ack.consumer_id;
+ await client.request("session.unsubscribe", {
+ session_id: this.sessionId,
+ consumer_kind: "plugin",
+ consumer_id: previousConsumerId,
+ plugin_id: this.pluginId,
+ generation: current.generation,
+ });
+ const next: OrderedReady = {
+ ...binding,
+ snapshotToken: ack.snapshot_token,
+ snapshotExpiresAt: ack.expires_at || binding.expiresAt,
+ resumeToken: ack.resume_token,
+ consumerId: ack.consumer_id,
+ watermark: ack.event_watermark,
+ };
+ this.currentResumeToken = ack.resume_token;
+ this.acknowledgedSequence = ack.event_watermark;
+ this.nextSequence = ack.event_watermark + 1;
+ this.stateGeneration += 1;
+ for (const sequence of this.pendingBySequence.keys()) {
+ if (sequence <= ack.event_watermark) this.pendingBySequence.delete(sequence);
+ }
+ this.buffered.length = 0;
+ this.committedSnapshots.clear();
+ this.readyPromise = Promise.resolve(next);
+ await this.notifyRebindListeners();
+ this.drainPending(this.sessionId);
+ return next;
+ }
+
+ private async notifyRebindListeners(): Promise {
+ await Promise.all(
+ [...this.rebindListeners].map((listener) => Promise.resolve().then(() => listener())),
+ );
+ }
+
+ private blockForPoison() {
+ this.sequenceBlocked = true;
+ this.poisonRebindPromise ??= this.rebindPastPoison()
+ .catch(() => undefined)
+ .finally(() => {
+ this.poisonRebindPromise = null;
+ });
+ }
+ private async rebindPastPoison() {
+ const ready = await this.ready();
+ const client = getWebSocketClient();
+ if (!client) return;
+ if (this.closed || this.terminal || !this.sessionId) return;
+ const ack = await client.request(SESSION_SUBSCRIBE_ACTION, {
+ session_id: this.sessionId,
+ consumer_kind: "plugin",
+ consumer_id: this.consumerId,
+ plugin_id: this.pluginId,
+ generation: ready.generation,
+ binding_token: ready.bindingToken,
+ last_seen_sequence: this.acknowledgedSequence,
+ resume_token: this.currentResumeToken,
+ replace_cursor: true,
+ });
+ if (!ack.success) {
+ if (ack.error.code === "session_removed") this.projectTerminalRemoval();
+ return;
+ }
+ this.consumerId = ack.consumer_id;
+ this.currentResumeToken = ack.resume_token;
+ this.acknowledgedSequence = ack.event_watermark;
+ this.nextSequence = ack.event_watermark + 1;
+ for (const sequence of this.pendingBySequence.keys()) {
+ if (sequence <= ack.event_watermark) this.pendingBySequence.delete(sequence);
+ }
+ this.buffered.length = 0;
+ this.committedSnapshots.clear();
+ this.stateGeneration += 1;
+ this.sequenceBlocked = true;
+ this.readyPromise = Promise.resolve({
+ ...ready,
+ snapshotToken: ack.snapshot_token,
+ snapshotExpiresAt: ack.expires_at || ready.snapshotExpiresAt,
+ resumeToken: ack.resume_token,
+ watermark: ack.event_watermark,
+ });
+ await this.notifyRebindListeners();
+ this.sequenceBlocked = false;
+ this.drainPending(this.sessionId);
+ }
+
+ private projectTerminalRemoval() {
+ if (!this.sessionId || this.terminal) return;
+ this.terminal = true;
+ const removedEvent: RawSessionEvent = {
+ type: "session.event",
+ protocol_version: 1,
+ event_type: SESSION_REMOVED_EVENT,
+ session_id: this.sessionId,
+ task_id: this.taskId,
+ sequence: this.acknowledgedSequence,
+ event_id: `terminal:${this.sessionId}`,
+ payload: { type: SESSION_REMOVED_EVENT, session_id: this.sessionId, task_id: this.taskId },
+ };
+ this.listeners.forEach((listener) => listener(removedEvent));
+ }
+
+ private async resume() {
+ const ready = await this.ready();
+ const client = getWebSocketClient();
+ if (!client || this.closed || this.terminal || !this.sessionId) return;
+ const ack = await client.request(SESSION_SUBSCRIBE_ACTION, {
+ session_id: this.sessionId,
+ consumer_kind: "plugin",
+ consumer_id: this.consumerId,
+ plugin_id: this.pluginId,
+ generation: ready.generation,
+ binding_token: ready.bindingToken,
+ last_seen_sequence: this.acknowledgedSequence,
+ resume_token: this.currentResumeToken,
+ });
+ if (ack.success) {
+ this.currentResumeToken = ack.resume_token;
+ const invalidResume = ack.result === "invalid_resume";
+ if (invalidResume) {
+ this.sequenceBlocked = true;
+ this.acknowledgedSequence = 0;
+ this.committedSnapshots.clear();
+ this.buffered.length = 0;
+ }
+ this.nextSequence =
+ ack.replay_from ?? Math.max(ack.event_watermark + 1, this.acknowledgedSequence + 1);
+ for (const sequence of this.pendingBySequence.keys()) {
+ if (sequence <= ack.event_watermark) this.pendingBySequence.delete(sequence);
+ }
+ if (!invalidResume) this.sequenceBlocked = false;
+ if (invalidResume) this.stateGeneration += 1;
+ this.readyPromise = Promise.resolve({
+ ...ready,
+ snapshotToken: ack.snapshot_token,
+ snapshotExpiresAt: ack.expires_at || ready.snapshotExpiresAt,
+ resumeToken: ack.resume_token,
+ watermark: ack.event_watermark,
+ });
+ if (invalidResume) {
+ await this.notifyRebindListeners();
+ this.sequenceBlocked = false;
+ this.drainPending(this.sessionId);
+ }
+ return;
+ }
+ if (ack.error.code === "session_removed") this.projectTerminalRemoval();
+ }
+}
+
+export function PluginConversationScopeProvider({
+ pluginId,
+ taskId,
+ sessionId,
+ generation = 0,
+ presentation = "desktop",
+ children,
+}: React.PropsWithChildren<{
+ pluginId: string;
+ taskId: string;
+ sessionId: string | null;
+ generation?: number;
+ presentation?: "desktop" | "mobile";
+}>) {
+ const controller = React.useMemo(
+ () => new AbortController(),
+ [generation, pluginId, presentation, sessionId, taskId],
+ );
+ const scope = React.useMemo(
+ () => new OrderedConversationScope(pluginId, taskId, sessionId, controller),
+ [controller, pluginId, sessionId, taskId],
+ );
+ React.useLayoutEffect(() => {
+ const client = getWebSocketClient();
+ let sawDisconnect = false;
+ const removeListener = client?.onRawSessionEvent((event) => scope.accept(event));
+ const removeStatusListener = client?.onConnectionStatus((status) => {
+ if (status !== "connected") {
+ sawDisconnect = true;
+ return;
+ }
+ if (sawDisconnect) {
+ sawDisconnect = false;
+ scope.reconnect();
+ }
+ });
+ return () => {
+ removeListener?.();
+ removeStatusListener?.();
+ scope.close();
+ controller.abort();
+ };
+ }, [controller, scope]);
+ return (
+ {children}
+ );
+}
diff --git a/apps/web/lib/plugins/duplicate-render.test.tsx b/apps/web/lib/plugins/duplicate-render.test.tsx
index e96c17958e..ca963e7cf4 100644
--- a/apps/web/lib/plugins/duplicate-render.test.tsx
+++ b/apps/web/lib/plugins/duplicate-render.test.tsx
@@ -30,6 +30,7 @@ function makeHostFactory(pluginId: string): PluginHostApi {
pluginId,
React,
jsx: React.createElement,
+ conversation: {} as PluginHostApi["conversation"],
store: { getState: () => ({}) as never, setState: () => {}, subscribe: () => () => {} },
context: {
getActiveWorkspaceId: () => undefined,
diff --git a/apps/web/lib/plugins/host-api.ts b/apps/web/lib/plugins/host-api.ts
index e231c970bc..1fc8f1c7b4 100644
--- a/apps/web/lib/plugins/host-api.ts
+++ b/apps/web/lib/plugins/host-api.ts
@@ -112,6 +112,10 @@ import { Combobox } from "@/components/combobox";
import { RichTextEditor, RichTextReadOnly } from "@/components/editors/tiptap/rich-text-editor";
import { PageTopbar } from "@/components/page-topbar";
import { TaskCreateDialog } from "@/components/task-create-dialog";
+import {
+ PromptMentionText as NativePromptMentionText,
+ usePromptMentionNames,
+} from "@/components/task/chat/messages/prompt-mention-components";
import { ChangeRequestList, ChangeRequestRow } from "@/components/integrations/change-request-list";
import type { ChangeRequestDetailProps } from "@/components/integrations/change-request-detail";
import { IntegrationStartTaskMenu } from "@/components/integrations/integration-start-task-menu";
@@ -148,6 +152,7 @@ import { readResolvedTheme, subscribeToThemeChanges } from "./theme";
import { composeWriterId, subscribeToUserStateChanges } from "./user-state-sync";
import { buildPluginContextApi } from "./plugin-context-api";
import { pluginTranslationNamespace } from "./plugin-translations";
+import { pluginConversationApi } from "./conversation-host";
import type {
PluginActionInput,
PluginActionOptions,
@@ -191,6 +196,21 @@ function PluginChangeRequestDetail(props: ChangeRequestDetailProps) {
);
}
+function PluginPromptMentionText({
+ text,
+ interactive = false,
+}: {
+ text: string;
+ interactive?: boolean;
+}) {
+ const promptNames = usePromptMentionNames();
+ return React.createElement(NativePromptMentionText, {
+ text,
+ promptNames,
+ focusable: interactive,
+ });
+}
+
/**
* Curated `@kandev/ui` subset exposed on `host.ui`, plus a handful of
* first-party app components (bottom of the map). Plugins must use these
@@ -350,6 +370,8 @@ const PLUGIN_UI: PluginUIApi & Record = {
// pixel-identical to the Plan panel. See rich-text-editor.tsx.
RichTextEditor,
RichTextReadOnly,
+ // - PromptMentionText: native prompt-reference parsing and chip rendering.
+ PromptMentionText: PluginPromptMentionText,
IntegrationAuthStatusBanner,
IntegrationEnabledControl: DraftedIntegrationEnabledControl,
SettingsSection,
@@ -499,6 +521,7 @@ export function buildHostApi(pluginId: string, storeApi: StoreApi): Pl
return getBackendConfig().apiBaseUrl;
},
},
+ conversation: pluginConversationApi,
ui: createPluginUIApi(pluginId),
useResponsiveBreakpoint,
// Getter, not a value captured at boot: a plugin built once at page load
diff --git a/apps/web/lib/plugins/host-initialize-timeout.test.ts b/apps/web/lib/plugins/host-initialize-timeout.test.ts
index c52a217a49..43bb8bfaf4 100644
--- a/apps/web/lib/plugins/host-initialize-timeout.test.ts
+++ b/apps/web/lib/plugins/host-initialize-timeout.test.ts
@@ -24,6 +24,7 @@ function makeHostFactory(pluginId: string): PluginHostApi {
pluginId,
React: {} as PluginHostApi["React"],
jsx: {} as PluginHostApi["jsx"],
+ conversation: {} as PluginHostApi["conversation"],
store: {
getState: () => ({}) as never,
setState: () => {},
diff --git a/apps/web/lib/plugins/host-lifecycle.test.ts b/apps/web/lib/plugins/host-lifecycle.test.ts
index 4a06f15a32..11797f53c3 100644
--- a/apps/web/lib/plugins/host-lifecycle.test.ts
+++ b/apps/web/lib/plugins/host-lifecycle.test.ts
@@ -1,7 +1,6 @@
import { describe, it, expect, vi, afterEach } from "vitest";
import { useResponsiveBreakpoint } from "@/hooks/use-responsive-breakpoint";
-import { pluginDestinations } from "@/lib/navigation/plugin-destinations";
-import { loadPlugins } from "./host";
+import { loadPlugins, unloadPlugin } from "./host";
import { pluginRegistry } from "./registry";
import type { ActivePlugin, PluginHostApi, PluginRegistry } from "./types";
@@ -29,6 +28,7 @@ function makeHostFactory(pluginId: string): PluginHostApi {
pluginId,
React: {} as PluginHostApi["React"],
jsx: {} as PluginHostApi["jsx"],
+ conversation: {} as PluginHostApi["conversation"],
store: {
getState: () => ({}) as never,
setState: () => {},
@@ -89,6 +89,10 @@ function activePlugin(overrides: Partial = {}): ActivePlugin {
};
}
+function registerFake(id: string, plugin: unknown) {
+ (window as unknown as FakeWindow).registerKandevPlugin(id, plugin);
+}
+
function fakeImporterFor(
bundles: Record void>,
): (url: string) => Promise {
@@ -186,8 +190,8 @@ describe("authoritative plugin lifecycle", () => {
});
});
-describe("authoritative plugin lifecycle — partial-initialization-failure retention", () => {
- it("keeps a sidebar-footer registration made before initialize() throws, and marks the plugin failed", async () => {
+describe("authoritative plugin lifecycle staging", () => {
+ it("discards a sidebar-footer registration when initialize() throws", async () => {
const initialize = vi.fn(async (registry: PluginRegistry) => {
registry.registerNavItem({
id: "nav-throw-a",
@@ -210,29 +214,13 @@ describe("authoritative plugin lifecycle — partial-initialization-failure rete
);
expect(pluginRegistry.getPluginLifecycle(PLUGIN_THROW_ID)?.status).toBe("failed");
- expect(pluginRegistry.getNavItems()).toContainEqual({
- id: "nav-throw-a",
- label: "Throw",
- path: "/throw-a",
- section: SIDEBAR_FOOTER_SECTION,
- });
- // The footer's manifest is built from getNavRegistrations() through
- // pluginDestinations() (see plugin-destinations.ts), which has no concept
- // of plugin lifecycle status — a "failed" plugin's already-registered item
- // maps to the "insights" section exactly like a "ready" plugin's would,
- // which is what makes it occupy a footer budget slot (spec.md:816's AC).
- const destinations = pluginDestinations(pluginRegistry.getNavRegistrations());
- expect(destinations).toContainEqual(
- expect.objectContaining({
- pluginItemId: "nav-throw-a",
- section: "insights",
- source: "plugin",
- }),
+ expect(pluginRegistry.getNavItems()).not.toContainEqual(
+ expect.objectContaining({ id: "nav-throw-a" }),
);
errorSpy.mockRestore();
});
- it("keeps a sidebar-footer registration made before initialize() times out, and marks the plugin failed", async () => {
+ it("discards a sidebar-footer registration when initialize() times out", async () => {
const initializeStarted = deferred();
const initializeGate = deferred();
const initialize = vi.fn(async (registry: PluginRegistry) => {
@@ -264,25 +252,139 @@ describe("authoritative plugin lifecycle — partial-initialization-failure rete
await load;
expect(pluginRegistry.getPluginLifecycle(PLUGIN_PARTIAL_TIMEOUT_ID)?.status).toBe("failed");
- expect(pluginRegistry.getNavItems()).toContainEqual({
- id: "nav-partial-timeout",
- label: "Partial",
- path: "/partial-timeout",
- section: SIDEBAR_FOOTER_SECTION,
- });
- // See the throw case above: pluginDestinations() has no lifecycle concept,
- // so a timed-out plugin's already-registered item still maps to "insights"
- // and occupies a footer budget slot exactly like a ready plugin's would.
- const destinations = pluginDestinations(pluginRegistry.getNavRegistrations());
- expect(destinations).toContainEqual(
- expect.objectContaining({
- pluginItemId: "nav-partial-timeout",
- section: "insights",
- source: "plugin",
- }),
+ expect(pluginRegistry.getNavItems()).not.toContainEqual(
+ expect.objectContaining({ id: "nav-partial-timeout" }),
);
initializeGate.resolve();
warnSpy.mockRestore();
});
});
+describe("plugin reload staging", () => {
+ const PLUGIN_RELOAD_ID = "plugin-reload-staging";
+
+ afterEach(() => {
+ unloadPlugin(PLUGIN_RELOAD_ID, { evictCache: true });
+ });
+
+ it("keeps the published runtime and contributions when a replacement fails", async () => {
+ const oldDestroy = vi.fn();
+ const importer = async (url: string) => {
+ if (url === "/old-bundle.js") {
+ registerFake(PLUGIN_RELOAD_ID, {
+ initialize: (registry: PluginRegistry) =>
+ registry.registerNavItem({ id: "old-nav", label: "Old", path: "/old" }),
+ destroy: oldDestroy,
+ });
+ return {};
+ }
+ registerFake(PLUGIN_RELOAD_ID, {
+ initialize: () => {
+ throw new Error("replacement failed");
+ },
+ });
+ return {};
+ };
+
+ await loadPlugins(
+ [activePlugin({ id: PLUGIN_RELOAD_ID, bundleUrl: "/old-bundle.js" })],
+ makeHostFactory,
+ importer,
+ );
+ await loadPlugins(
+ [activePlugin({ id: PLUGIN_RELOAD_ID, bundleUrl: "/new-bundle.js" })],
+ makeHostFactory,
+ importer,
+ );
+
+ expect(pluginRegistry.getNavItems()).toContainEqual(expect.objectContaining({ id: "old-nav" }));
+ expect(oldDestroy).not.toHaveBeenCalled();
+ expect(pluginRegistry.getPluginLifecycle(PLUGIN_RELOAD_ID)?.status).toBe("ready");
+ });
+});
+
+describe("plugin registration staging", () => {
+ const PLUGIN_STAGE_ID = "plugin-registration-staging";
+
+ afterEach(() => {
+ unloadPlugin(PLUGIN_STAGE_ID, { evictCache: true });
+ pluginRegistry.unregisterPlugin("foreign-registration");
+ });
+
+ it("ignores foreign and late registrations without changing the matching bundle cache", async () => {
+ const importer = vi.fn(async (_url: string) => {
+ const register = (window as unknown as FakeWindow).registerKandevPlugin;
+ register("foreign-registration", {
+ initialize: (registry: PluginRegistry) =>
+ registry.registerNavItem({ id: "foreign-nav", label: "Foreign", path: "/foreign" }),
+ });
+ register(PLUGIN_STAGE_ID, {
+ initialize: (registry: PluginRegistry) =>
+ registry.registerNavItem({ id: "stage-nav", label: "Stage", path: "/stage" }),
+ });
+ (window as unknown as { lateRegister?: typeof register }).lateRegister = register;
+ return {};
+ });
+
+ await loadPlugins(
+ [activePlugin({ id: PLUGIN_STAGE_ID, bundleUrl: "/stage-bundle.js" })],
+ makeHostFactory,
+ importer,
+ );
+ (window as unknown as { lateRegister?: typeof registerFake }).lateRegister?.(PLUGIN_STAGE_ID, {
+ initialize: (registry: PluginRegistry) =>
+ registry.registerNavItem({ id: "late-nav", label: "Late", path: "/late" }),
+ });
+ unloadPlugin(PLUGIN_STAGE_ID);
+ await loadPlugins(
+ [activePlugin({ id: PLUGIN_STAGE_ID, bundleUrl: "/stage-bundle.js" })],
+ makeHostFactory,
+ importer,
+ );
+
+ expect(importer).toHaveBeenCalledTimes(1);
+ expect(pluginRegistry.getNavItems()).toContainEqual(
+ expect.objectContaining({ id: "stage-nav" }),
+ );
+ expect(pluginRegistry.getNavItems()).not.toContainEqual(
+ expect.objectContaining({ id: "foreign-nav" }),
+ );
+ expect(pluginRegistry.getNavItems()).not.toContainEqual(
+ expect.objectContaining({ id: "late-nav" }),
+ );
+ });
+
+ it("imports a changed bundle URL instead of reusing the prior registration", async () => {
+ const importer = vi.fn(async (url: string) => {
+ registerFake(PLUGIN_STAGE_ID, {
+ initialize: (registry: PluginRegistry) =>
+ registry.registerNavItem({
+ id: url === "/stage-v1.js" ? "stage-v1-nav" : "stage-v2-nav",
+ label: "Stage",
+ path: "/stage",
+ }),
+ });
+ return {};
+ });
+
+ await loadPlugins(
+ [activePlugin({ id: PLUGIN_STAGE_ID, bundleUrl: "/stage-v1.js" })],
+ makeHostFactory,
+ importer,
+ );
+ unloadPlugin(PLUGIN_STAGE_ID);
+ await loadPlugins(
+ [activePlugin({ id: PLUGIN_STAGE_ID, bundleUrl: "/stage-v2.js" })],
+ makeHostFactory,
+ importer,
+ );
+
+ expect(importer).toHaveBeenCalledTimes(2);
+ expect(pluginRegistry.getNavItems()).toContainEqual(
+ expect.objectContaining({ id: "stage-v2-nav" }),
+ );
+ expect(pluginRegistry.getNavItems()).not.toContainEqual(
+ expect.objectContaining({ id: "stage-v1-nav" }),
+ );
+ });
+});
diff --git a/apps/web/lib/plugins/host-reenable.test.ts b/apps/web/lib/plugins/host-reenable.test.ts
index d5c51fc205..4235b4dd45 100644
--- a/apps/web/lib/plugins/host-reenable.test.ts
+++ b/apps/web/lib/plugins/host-reenable.test.ts
@@ -25,6 +25,7 @@ function makeHostFactory(pluginId: string): PluginHostApi {
pluginId,
React: {} as PluginHostApi["React"],
jsx: {} as PluginHostApi["jsx"],
+ conversation: {} as PluginHostApi["conversation"],
store: {
getState: () => ({}) as never,
setState: () => {},
diff --git a/apps/web/lib/plugins/host-runtime-resources.test.ts b/apps/web/lib/plugins/host-runtime-resources.test.ts
index d13cb76e0c..19f3247bb5 100644
--- a/apps/web/lib/plugins/host-runtime-resources.test.ts
+++ b/apps/web/lib/plugins/host-runtime-resources.test.ts
@@ -9,6 +9,7 @@ function makeHost(setIntegrationEnabled: PluginHostApi["setIntegrationEnabled"])
pluginId: "plugin-a",
React: {} as PluginHostApi["React"],
jsx: {} as PluginHostApi["jsx"],
+ conversation: {} as PluginHostApi["conversation"],
store: {
getState: () => ({}) as never,
setState: () => {},
@@ -88,4 +89,52 @@ describe("generationFencedHost integration state", () => {
true,
);
});
+
+ it("returns inert conversation capabilities after generation revocation", async () => {
+ let current = true;
+ const host = makeHost(vi.fn() as PluginHostApi["setIntegrationEnabled"]);
+ const loadMore = vi.fn(async () => 1);
+ const retry = vi.fn();
+ host.conversation = {
+ useSessionMessages: () => ({
+ messages: [{ id: "message-1" }] as never,
+ loading: false,
+ hydrated: true,
+ loadingMore: false,
+ error: null,
+ hasMore: true,
+ removed: false,
+ loadMore,
+ retry,
+ }),
+ useSessionTurns: () => ({
+ turns: [{ id: "turn-1" }] as never,
+ loading: false,
+ hydrated: true,
+ error: null,
+ removed: false,
+ retry,
+ }),
+ useMessageFavorite: () => true,
+ };
+ const fenced = generationFencedHost(
+ host,
+ () => current,
+ new PluginLoadResources(host.pluginId),
+ );
+
+ expect(
+ fenced.conversation.useSessionMessages({ sessionId: "session-1" }).messages,
+ ).toHaveLength(1);
+ current = false;
+ const staleMessages = fenced.conversation.useSessionMessages({ sessionId: "session-1" });
+ const staleTurns = fenced.conversation.useSessionTurns("session-1");
+
+ expect(staleMessages.messages).toEqual([]);
+ expect(await staleMessages.loadMore()).toBe(0);
+ staleMessages.retry();
+ staleTurns.retry();
+ expect(retry).not.toHaveBeenCalled();
+ expect(fenced.conversation.useMessageFavorite("session-1", "message-1")).toBe(false);
+ });
});
diff --git a/apps/web/lib/plugins/host-runtime-resources.ts b/apps/web/lib/plugins/host-runtime-resources.ts
index dccd6ff676..fe07e8918e 100644
--- a/apps/web/lib/plugins/host-runtime-resources.ts
+++ b/apps/web/lib/plugins/host-runtime-resources.ts
@@ -2,6 +2,7 @@ import { reviewItemId } from "@/components/task/review-selection";
import { reviewPanelId } from "@/lib/state/dockview-panel-actions";
import { useDockviewStore } from "@/lib/state/dockview-store";
import type {
+ PluginConversationApi,
PluginHostApi,
PluginModalHandle,
PluginStorageApi,
@@ -111,6 +112,7 @@ export function generationFencedHost(
pluginId: host.pluginId,
React: host.React,
jsx: host.jsx,
+ conversation: generationFencedConversation(host.conversation, isCurrent),
store: { ...host.store, setState, subscribe },
context: generationFencedContext(host, isCurrent, resources),
api: {
@@ -154,6 +156,45 @@ export function generationFencedHost(
};
}
+function generationFencedConversation(
+ conversation: PluginConversationApi,
+ isCurrent: () => boolean,
+): PluginConversationApi {
+ return {
+ useSessionMessages(query) {
+ const state = conversation.useSessionMessages(query);
+ if (isCurrent()) return state;
+ return {
+ messages: [],
+ loading: false,
+ hydrated: false,
+ loadingMore: false,
+ error: null,
+ hasMore: false,
+ removed: false,
+ loadMore: async () => 0,
+ retry: () => {},
+ };
+ },
+ useSessionTurns(sessionId, taskId) {
+ const state = conversation.useSessionTurns(sessionId, taskId);
+ if (isCurrent()) return state;
+ return {
+ turns: [],
+ loading: false,
+ hydrated: false,
+ error: null,
+ removed: false,
+ retry: () => {},
+ };
+ },
+ useMessageFavorite(sessionId, messageId) {
+ const favorite = conversation.useMessageFavorite(sessionId, messageId);
+ return isCurrent() ? favorite : false;
+ },
+ };
+}
+
function generationFencedContext(
host: PluginHostApi,
isCurrent: () => boolean,
diff --git a/apps/web/lib/plugins/host.repository-providers.test.ts b/apps/web/lib/plugins/host.repository-providers.test.ts
index 03a77c263d..3b7c6618dc 100644
--- a/apps/web/lib/plugins/host.repository-providers.test.ts
+++ b/apps/web/lib/plugins/host.repository-providers.test.ts
@@ -20,6 +20,7 @@ function makeHostFactory(pluginId: string): PluginHostApi {
pluginId,
React: {} as PluginHostApi["React"],
jsx: {} as PluginHostApi["jsx"],
+ conversation: {} as PluginHostApi["conversation"],
store: {
getState: () => ({}) as never,
setState: () => {},
diff --git a/apps/web/lib/plugins/host.test.ts b/apps/web/lib/plugins/host.test.ts
index ec79b28720..3329e781d3 100644
--- a/apps/web/lib/plugins/host.test.ts
+++ b/apps/web/lib/plugins/host.test.ts
@@ -28,6 +28,7 @@ function makeHostFactory(pluginId: string): PluginHostApi {
pluginId,
React: {} as PluginHostApi["React"],
jsx: {} as PluginHostApi["jsx"],
+ conversation: {} as PluginHostApi["conversation"],
store,
context: buildPluginContextApi(store),
api: {
@@ -195,9 +196,13 @@ describe("loadPlugins — bundle lifecycle", () => {
errorSpy.mockRestore();
});
- it("keeps registrations made before an initialize failure (spec.md:816)", async () => {
+ it("discards a failed generation without publishing partial registrations", async () => {
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
const pluginId = "plugin-partial-initialize";
+ const observedNavIds: string[][] = [];
+ const unsubscribe = pluginRegistry.subscribe(() => {
+ observedNavIds.push(pluginRegistry.getNavItems().map((item) => item.id));
+ });
const importer = fakeImporterFor({
"/partial-bundle.js": (win) =>
(win as unknown as FakeWindow).registerKandevPlugin(pluginId, {
@@ -214,12 +219,12 @@ describe("loadPlugins — bundle lifecycle", () => {
importer,
);
- expect(pluginRegistry.getNavItems()).toContainEqual({
- id: "partial-nav",
- label: "Partial",
- path: "/partial",
- });
- pluginRegistry.unregisterPlugin(pluginId);
+ expect(pluginRegistry.getNavItems()).not.toContainEqual(
+ expect.objectContaining({ id: "partial-nav" }),
+ );
+ expect(observedNavIds.every((ids) => !ids.includes("partial-nav"))).toBe(true);
+ expect(pluginRegistry.getPluginLifecycle(pluginId)?.status).toBe("failed");
+ unsubscribe();
errorSpy.mockRestore();
});
@@ -522,7 +527,7 @@ describe("generation fence forwards every registry method, not just the slot one
});
});
-describe("overlapping loads for the same plugin: newest-initiated load wins", () => {
+describe("same-plugin loads serialize bundle registration and fence initialization", () => {
const PLUGIN_CONC_A_ID = "plugin-conc-a";
const PLUGIN_CONC_B_ID = "plugin-conc-b";
const SLOT = "chat-input-actions";
@@ -548,7 +553,7 @@ describe("overlapping loads for the same plugin: newest-initiated load wins", ()
const NewWidget = () => null;
const oldImportGate = deferred();
- // The older boot import resolves only after the gate — i.e. last.
+ // The older import parks on the gate.
const oldImporter = async (_url: string) => {
await oldImportGate.promise;
registerFake(PLUGIN_CONC_A_ID, {
@@ -563,22 +568,17 @@ describe("overlapping loads for the same plugin: newest-initiated load wins", ()
return {};
};
- // Older load starts first (claims the earlier generation) but parks on its
- // import; the newer load then runs to completion.
+ // Same-plugin registration is serialized so each global callback has one
+ // unambiguous staging owner.
const oldLoad = loadPlugins(
[activePlugin({ id: PLUGIN_CONC_A_ID })],
makeHostFactory,
oldImporter,
);
- await loadPlugins([activePlugin({ id: PLUGIN_CONC_A_ID })], makeHostFactory, newImporter);
- expect(pluginRegistry.getSlotComponents(SLOT)).toEqual([NewWidget]);
- expect(pluginRegistry.getPluginLifecycle(PLUGIN_CONC_A_ID)?.status).toBe("ready");
-
- // The stale import finally resolves — it must bail before touching the
- // registry, leaving the newer registration intact (no unregister, no OldWidget).
oldImportGate.resolve();
await oldLoad;
-
+ unloadPlugin(PLUGIN_CONC_A_ID, { evictCache: true });
+ await loadPlugins([activePlugin({ id: PLUGIN_CONC_A_ID })], makeHostFactory, newImporter);
expect(pluginRegistry.getSlotComponents(SLOT)).toEqual([NewWidget]);
expect(pluginRegistry.getPluginLifecycle(PLUGIN_CONC_A_ID)?.status).toBe("ready");
});
diff --git a/apps/web/lib/plugins/host.ts b/apps/web/lib/plugins/host.ts
index 401e062ee1..121a15c70f 100644
--- a/apps/web/lib/plugins/host.ts
+++ b/apps/web/lib/plugins/host.ts
@@ -9,11 +9,11 @@
* registration, or throwing `initialize`) is logged and swallowed — it never
* breaks boot or blocks other plugins.
*
- * `registeredPlugins` is never cleared on disable — only on a fresh import
- * (see `resolveRegistration`). The browser's ES module cache means a repeat
- * `import(bundleUrl)` after disable would resolve without re-running the
- * bundle's top-level `registerKandevPlugin` call, so re-enabling in the same
- * tab must reuse the cached registration instead of relying on re-import.
+ * `registeredPlugins` is retained by bundle identity across disable/re-enable
+ * cycles, but a changed bundle URL always gets a fresh module registration.
+ * The global callback is accepted only while the matching bundle import has an
+ * open registration stage, preventing late or foreign bundles from poisoning
+ * the cache.
*/
import { getBackendConfig } from "@/lib/config";
import { pluginModalManager } from "./modal-manager";
@@ -73,8 +73,22 @@ type PluginGlobalWindow = Window & {
registerKandevPlugin?: (id: string, plugin: KandevPlugin) => void;
};
-/** Bundles registered via `window.registerKandevPlugin`, keyed by pluginId. */
-const registeredPlugins = new Map();
+type RegistrationCacheEntry = {
+ bundleUrl: string;
+ plugin: KandevPlugin;
+};
+
+const registeredPlugins = new Map();
+
+type RegistrationStage = {
+ pluginId: string;
+ bundleUrl: string;
+ plugin?: KandevPlugin;
+ open: boolean;
+};
+
+let registrationStage: RegistrationStage | undefined;
+let registrationQueue = Promise.resolve();
/**
* Latest load "generation" claimed per pluginId. `loadPlugin` claims a fresh
@@ -97,6 +111,9 @@ type ActivePluginRuntime = {
/** Currently initialized (or initializing) runtime per plugin id. */
const activePluginRuntimes = new Map();
+/** Generation currently published to consumers; staged replacements do not change it. */
+const publishedGenerations = new Map();
+
/** Claims and returns a new, strictly-increasing load generation for `id`. */
function claimLoadGeneration(id: string): number {
const next = (loadGenerations.get(id) ?? 0) + 1;
@@ -109,36 +126,64 @@ function isCurrentLoad(id: string, generation: number): boolean {
return loadGenerations.get(id) === generation;
}
-/**
- * Wraps a scoped `PluginRegistry` so every register* call is dropped once this
- * load has been superseded by a newer one (`isCurrent()` is false). Guards the
- * window where a plugin registers *after* an `await` inside `initialize()`: a
- * stale async initializer must not append onto the successor's registrations.
- *
- * Wraps every method reflectively rather than naming each one, so any register*
- * added to the `PluginRegistry` contract (e.g. `registerKeybinding`) is fenced
- * automatically instead of being silently dropped from the forwarded object.
- */
-function generationFencedRegistry(
+function stagedGenerationRegistry(
registry: PluginRegistry,
isCurrent: () => boolean,
-): PluginRegistry {
- const fenced: Record = {};
+): { registry: PluginRegistry; commit: () => void } {
+ const pending: Array<() => void> = [];
+ const staged: Record = {};
for (const [key, value] of Object.entries(registry)) {
- fenced[key] =
+ staged[key] =
typeof value === "function"
? (...args: unknown[]) => {
- if (isCurrent()) (value as (...callArgs: unknown[]) => unknown)(...args);
+ if (isCurrent()) {
+ pending.push(() => (value as (...callArgs: unknown[]) => unknown)(...args));
+ }
}
: value;
}
- return fenced as unknown as PluginRegistry;
+ return {
+ registry: staged as unknown as PluginRegistry,
+ commit: () => pending.forEach((registration) => registration()),
+ };
+}
+
+function isCurrentPublished(id: string, generation: number): boolean {
+ return publishedGenerations.get(id) === generation;
+}
+
+function failPluginGeneration(
+ pluginId: string,
+ generation: number,
+ preservePublished: boolean,
+ restorePublishedMetadata?: () => void,
+) {
+ pluginRegistry.runAtomicMutation(() => {
+ if (preservePublished) {
+ restorePublishedMetadata?.();
+ pluginRegistry.markPluginReady(pluginId, generation);
+ } else {
+ pluginRegistry.unregisterPlugin(pluginId);
+ restorePublishedMetadata?.();
+ pluginRegistry.markPluginFailed(pluginId, generation);
+ }
+ });
+}
+
+function setPluginDeclarations(plugin: ActivePlugin): void {
+ if (plugin.repositoryProviderIds) {
+ pluginRegistry.setDeclaredRepositoryProviderIds(plugin.id, plugin.repositoryProviderIds);
+ } else {
+ pluginRegistry.clearDeclaredRepositoryProviderIds(plugin.id);
+ }
}
/** Defines `window.registerKandevPlugin` before any bundle loads. Idempotent. */
export function installPluginGlobal(win: Window = window): void {
(win as PluginGlobalWindow).registerKandevPlugin = (id, plugin) => {
- registeredPlugins.set(id, plugin);
+ const stage = registrationStage;
+ if (!stage || !stage.open || stage.pluginId !== id || stage.plugin) return;
+ stage.plugin = plugin;
};
}
@@ -165,6 +210,7 @@ export async function loadPlugins(
}
}
+// eslint-disable-next-line max-lines-per-function -- Plugin loading keeps the guarded lifecycle in one transaction.
async function loadPlugin(
plugin: ActivePlugin,
hostFactory: PluginHostFactory,
@@ -172,73 +218,63 @@ async function loadPlugin(
initTimeoutMs: number,
): Promise {
const { apiBaseUrl } = getBackendConfig();
- // Claim a generation before the (awaited) import so entry order — not
- // import-resolve order — decides which load owns the registry.
const generation = claimLoadGeneration(plugin.id);
- // A replacement generation owns the id immediately. Abort and destroy the
- // prior runtime before loading new code so its requests/listeners cannot run
- // concurrently with the successor.
- deactivatePluginRuntime(plugin.id);
+ const previousRuntime = activePluginRuntimes.get(plugin.id);
+ const previousPluginName = pluginRegistry.getPluginName(plugin.id);
+ const previousProviderIds = pluginRegistry.getDeclaredRepositoryProviderIds(plugin.id);
+ const restorePublishedMetadata = () => {
+ pluginRegistry.restorePluginName(plugin.id, previousPluginName);
+ if (previousProviderIds) {
+ pluginRegistry.setDeclaredRepositoryProviderIds(plugin.id, previousProviderIds);
+ } else {
+ pluginRegistry.clearDeclaredRepositoryProviderIds(plugin.id);
+ }
+ };
pluginRegistry.markPluginLoading(plugin.id, generation);
let generationOpen = true;
+ let resources: PluginLoadResources | undefined;
+ let registeredPlugin: KandevPlugin | undefined;
const isActiveGeneration = () => generationOpen && isCurrentLoad(plugin.id, generation);
try {
- injectStyles(plugin.id, plugin.styleUrls, apiBaseUrl);
- const registered = await resolveRegistration(plugin, importer, apiBaseUrl);
- if (!registered) {
+ injectStyles(plugin.id, plugin.styleUrls, apiBaseUrl, generation);
+ registeredPlugin = await resolveRegistration(
+ plugin,
+ importer,
+ apiBaseUrl,
+ previousRuntime?.plugin,
+ );
+ if (!registeredPlugin) {
console.error(`[plugins] "${plugin.id}" bundle did not call registerKandevPlugin`);
generationOpen = false;
if (isCurrentLoad(plugin.id, generation)) {
- pluginRegistry.markPluginFailed(plugin.id, generation);
+ failPluginGeneration(
+ plugin.id,
+ generation,
+ Boolean(previousRuntime),
+ restorePublishedMetadata,
+ );
revokeFailedLoad(plugin.id, generation);
}
return;
}
- // A newer load for this plugin started while we awaited the import — it now
- // owns the registry. Bail before mutating anything so this stale load can't
- // revoke the successor's registrations or initialize an older bundle over
- // them (the boot-vs-update race Codex flagged).
if (!isCurrentLoad(plugin.id, generation)) {
generationOpen = false;
+ removeStyles(plugin.id, generation);
return;
}
- const resources = new PluginLoadResources(plugin.id);
- activePluginRuntimes.set(plugin.id, { generation, plugin: registered, resources });
+ resources = new PluginLoadResources(plugin.id);
const host = generationFencedHost(
hostFactory(plugin.id),
- () => isCurrentLoad(plugin.id, generation),
+ () => isActiveGeneration() || isCurrentPublished(plugin.id, generation),
resources,
);
- // Idempotent (re)load. The nav/route/slot registry is append-only, so
- // running a plugin's initialize() a second time while its previous
- // registrations are still live leaves duplicates — e.g. a plugin's
- // chat-input-actions icon rendered twice. The disable/update paths already
- // call unloadPlugin() first, but boot does not, and it can re-enter for a
- // plugin that is already registered: a boot race (bootPlugins' fire-and-
- // forget loadPlugins still in flight when an install/update reload runs), a
- // dev HMR re-boot (fresh bootedStores guard against the persistent registry
- // singleton), or a fresh store instance. Because resolveRegistration reuses
- // the cached bundle registration, that re-entry re-runs initialize() and
- // re-registers on top of the old entries. Revoke this plugin's prior
- // registrations here so a reload always converges to exactly one set,
- // whatever the caller did — a no-op on a genuine first load.
- pluginRegistry.unregisterPlugin(plugin.id);
- // Newer boot payloads carry manifest-owned provider IDs. Set them after
- // revoking prior state and before plugin initialize(), so a re-enable
- // cannot retain stale declarations and registration is checked eagerly.
- // Omit this call for older payloads to preserve their existing registry API.
- if (plugin.repositoryProviderIds) {
- pluginRegistry.setDeclaredRepositoryProviderIds(plugin.id, plugin.repositoryProviderIds);
+ const scopedRegistry = pluginRegistry.forPlugin(plugin.id, plugin.name);
+ if (isCurrentLoad(plugin.id, generation)) {
+ pluginRegistry.runAtomicMutation(() => setPluginDeclarations(plugin));
}
- // Fence the scoped registry on this generation so that if an even-newer
- // load supersedes us while initialize() is awaiting, a plugin that
- // registers post-await can't append onto the successor.
- const registry = generationFencedRegistry(
- pluginRegistry.forPlugin(plugin.id, plugin.name),
- isActiveGeneration,
- );
+ const staged = stagedGenerationRegistry(scopedRegistry, isActiveGeneration);
const result = await raceTimeout(
- Promise.resolve(registered.initialize(registry, host)),
+ Promise.resolve(registeredPlugin.initialize(staged.registry, host)),
initTimeoutMs,
() => {
console.warn(
@@ -247,85 +283,160 @@ async function loadPlugin(
},
);
generationOpen = false;
- if (isCurrentLoad(plugin.id, generation)) {
- if (result.timedOut) {
- pluginRegistry.markPluginFailed(plugin.id, generation);
- revokeFailedLoad(plugin.id, generation);
- } else {
- pluginRegistry.markPluginReady(plugin.id, generation);
- }
+ if (!isCurrentLoad(plugin.id, generation)) {
+ revokeFailedLoad(plugin.id, generation, resources, registeredPlugin);
+ return;
+ }
+ if (result.timedOut) {
+ failPluginGeneration(
+ plugin.id,
+ generation,
+ Boolean(previousRuntime),
+ restorePublishedMetadata,
+ );
+ revokeFailedLoad(plugin.id, generation, resources, registeredPlugin);
+ return;
+ }
+ publishPluginGeneration(plugin, generation, staged, registeredPlugin, resources);
+ if (previousRuntime) {
+ retireRuntime(plugin.id, previousRuntime);
+ removeStyles(plugin.id, previousRuntime.generation);
}
} catch (error) {
generationOpen = false;
if (isCurrentLoad(plugin.id, generation)) {
- pluginRegistry.markPluginFailed(plugin.id, generation);
+ failPluginGeneration(
+ plugin.id,
+ generation,
+ Boolean(previousRuntime),
+ restorePublishedMetadata,
+ );
}
console.error(`[plugins] failed to load plugin "${plugin.id}"`, error);
- revokeFailedLoad(plugin.id, generation);
+ revokeFailedLoad(plugin.id, generation, resources, registeredPlugin);
}
}
/**
- * Removes a failed generation without disturbing a newer concurrent load.
- * Leaves the plugin's registry entries (nav items, routes, etc.) in place: a
- * registration made before `initialize()` threw or timed out must survive —
- * only the runtime (resources, styles, modals) is torn down. `loadPlugin`
- * already marked the plugin `"failed"` before calling this.
+ * Publishes one plugin generation under the registry's atomic mutation: the
+ * previous registration set is revoked and the staged registrations commit as
+ * one unit, so a partial failure rolls the whole generation back.
*/
-function revokeFailedLoad(pluginId: string, generation: number): void {
- if (!isCurrentLoad(pluginId, generation)) return;
- deactivatePluginRuntime(pluginId, generation, { unregister: false });
- // Fence delayed registrations from an initializer that timed out.
- claimLoadGeneration(pluginId);
-}
-
-/**
- * Revokes one active runtime without changing its published lifecycle state.
- * Pass `unregister: false` to keep the plugin's existing registry entries —
- * used by the failed-load path (see `revokeFailedLoad`) so a nav item
- * registered before `initialize()` failed is retained, per the
- * partial-initialization-failure retention contract (spec.md's AC).
- */
-function deactivatePluginRuntime(
- pluginId: string,
- expectedGeneration?: number,
- options?: { unregister?: boolean },
+function publishPluginGeneration(
+ plugin: ActivePlugin,
+ generation: number,
+ staged: { commit: () => void },
+ registeredPlugin: KandevPlugin,
+ resources: PluginLoadResources,
+): void {
+ pluginRegistry.runAtomicMutation(() => {
+ pluginRegistry.unregisterPlugin(plugin.id);
+ pluginRegistry.restorePluginName(plugin.id, plugin.name);
+ setPluginDeclarations(plugin);
+ staged.commit();
+ activePluginRuntimes.set(plugin.id, {
+ generation,
+ plugin: registeredPlugin,
+ resources,
+ });
+ publishedGenerations.set(plugin.id, generation);
+ pluginRegistry.markPluginReady(plugin.id, generation);
+ });
+}
+
+/** Removes a failed generation without touching the published runtime. */
+function revokeFailedLoad(
+ pluginId: string,
+ generation: number,
+ resources?: PluginLoadResources,
+ plugin?: KandevPlugin,
): void {
- if (expectedGeneration !== undefined && !isCurrentLoad(pluginId, expectedGeneration)) return;
const runtime = activePluginRuntimes.get(pluginId);
- if (runtime && expectedGeneration !== undefined && runtime.generation !== expectedGeneration) {
- return;
- }
- if (runtime) {
+ if (runtime?.generation === generation) {
activePluginRuntimes.delete(pluginId);
- runtime.resources.revoke();
+ retireRuntime(pluginId, runtime);
+ } else if (resources) {
+ resources.revoke();
try {
- runtime.plugin.destroy?.();
+ plugin?.destroy?.();
} catch (error) {
console.error(`[plugins] error destroying plugin "${pluginId}"`, error);
}
+ pluginModalManager.closeAllForPlugin(pluginId);
}
- if (options?.unregister ?? true) {
- pluginRegistry.unregisterPlugin(pluginId);
+ removeStyles(pluginId, generation);
+}
+
+function retireRuntime(pluginId: string, runtime: ActivePluginRuntime): void {
+ runtime.resources.revoke();
+ try {
+ runtime.plugin.destroy?.();
+ } catch (error) {
+ console.error(`[plugins] error destroying plugin "${pluginId}"`, error);
}
pluginModalManager.closeAllForPlugin(pluginId);
+}
+
+/** Revokes one published runtime and its contributions. */
+function deactivatePluginRuntime(pluginId: string): void {
+ const runtime = activePluginRuntimes.get(pluginId);
+ if (runtime) {
+ activePluginRuntimes.delete(pluginId);
+ publishedGenerations.delete(pluginId);
+ retireRuntime(pluginId, runtime);
+ }
+ pluginRegistry.unregisterPlugin(pluginId);
+ pluginModalManager.closeAllForPlugin(pluginId);
removeStyles(pluginId);
}
/**
- * Returns the plugin's registration, importing the bundle only when it
- * isn't already cached from a prior load in this tab (see module doc for
- * why re-enable must not blindly re-import).
+ * Returns the plugin's registration, importing the bundle only when the
+ * resolved bundle URL is not already cached in this tab.
*/
async function resolveRegistration(
plugin: ActivePlugin,
importer: BundleImporter,
apiBaseUrl: string,
+ previousRuntimePlugin?: KandevPlugin,
): Promise {
- const cached = registeredPlugins.get(plugin.id);
+ const bundleUrl = resolvePluginUrl(plugin.bundleUrl, apiBaseUrl);
+ const cachedRegistration = () => {
+ const cached = registeredPlugins.get(plugin.id);
+ if (cached?.bundleUrl !== bundleUrl) return undefined;
+ return cached.plugin === previousRuntimePlugin ? { ...cached.plugin } : cached.plugin;
+ };
+ const cached = cachedRegistration();
if (cached) return cached;
- await importer(resolvePluginUrl(plugin.bundleUrl, apiBaseUrl));
- return registeredPlugins.get(plugin.id);
+
+ const previousRegistration = registrationQueue;
+ let releaseRegistration!: () => void;
+ const registrationTurn = new Promise((resolve) => {
+ releaseRegistration = resolve;
+ });
+ const queuedRegistration = previousRegistration.then(() => registrationTurn);
+ registrationQueue = queuedRegistration;
+ try {
+ await previousRegistration;
+ const queuedCached = cachedRegistration();
+ if (queuedCached) return queuedCached;
+
+ const stage: RegistrationStage = { pluginId: plugin.id, bundleUrl, open: true };
+ registrationStage = stage;
+ try {
+ await importer(bundleUrl);
+ if (stage.plugin) {
+ registeredPlugins.set(plugin.id, { bundleUrl, plugin: stage.plugin });
+ }
+ return stage.plugin;
+ } finally {
+ stage.open = false;
+ if (registrationStage === stage) registrationStage = undefined;
+ }
+ } finally {
+ releaseRegistration();
+ if (registrationQueue === queuedRegistration) registrationQueue = Promise.resolve();
+ }
}
/**
@@ -339,20 +450,30 @@ function resolvePluginUrl(url: string, apiBaseUrl: string): string {
return `${apiBaseUrl}${url}`;
}
-function injectStyles(pluginId: string, styleUrls: string[] | undefined, apiBaseUrl: string): void {
+function injectStyles(
+ pluginId: string,
+ styleUrls: string[] | undefined,
+ apiBaseUrl: string,
+ generation: number,
+): void {
if (!styleUrls) return;
for (const href of styleUrls) {
const link = document.createElement("link");
link.rel = "stylesheet";
link.href = resolvePluginUrl(href, apiBaseUrl);
link.dataset.pluginId = pluginId;
+ link.dataset.pluginGeneration = String(generation);
document.head.appendChild(link);
}
}
-/** Removes every `` this plugin injected via `injectStyles`. */
-function removeStyles(pluginId: string): void {
- document.querySelectorAll(`link[data-plugin-id="${pluginId}"]`).forEach((link) => link.remove());
+/** Removes one generation's styles, or every style during explicit unload. */
+function removeStyles(pluginId: string, generation?: number): void {
+ const selector =
+ generation === undefined
+ ? `link[data-plugin-id="${pluginId}"]`
+ : `link[data-plugin-id="${pluginId}"][data-plugin-generation="${generation}"]`;
+ document.querySelectorAll(selector).forEach((link) => link.remove());
}
/**
diff --git a/apps/web/lib/plugins/plugin-translations.ts b/apps/web/lib/plugins/plugin-translations.ts
index 55ef26e641..fb16fc3645 100644
--- a/apps/web/lib/plugins/plugin-translations.ts
+++ b/apps/web/lib/plugins/plugin-translations.ts
@@ -6,6 +6,33 @@ const MAX_MESSAGES_PER_LOCALE = 1_000;
const MAX_MESSAGE_LENGTH = 4_096;
const registeredLocales = new Map>();
+export type PluginTranslationsSnapshot = Map>>;
+
+export function snapshotPluginTranslations(): PluginTranslationsSnapshot {
+ return new Map(
+ [...registeredLocales].map(([pluginId, locales]) => [
+ pluginId,
+ new Map(
+ [...locales].map((locale) => [
+ locale,
+ { ...(i18n.getResourceBundle(locale, pluginTranslationNamespace(pluginId)) ?? {}) },
+ ]),
+ ),
+ ]),
+ );
+}
+
+export function restorePluginTranslations(snapshot: PluginTranslationsSnapshot): void {
+ for (const pluginId of registeredLocales.keys()) unregisterPluginTranslations(pluginId);
+ for (const [pluginId, locales] of snapshot) {
+ const registered = new Set();
+ for (const [locale, catalog] of locales) {
+ i18n.addResourceBundle(locale, pluginTranslationNamespace(pluginId), catalog, false, true);
+ registered.add(locale);
+ }
+ registeredLocales.set(pluginId, registered);
+ }
+}
export function pluginTranslationNamespace(pluginId: string): string {
return `plugin-${pluginId}`;
diff --git a/apps/web/lib/plugins/registry-provider-lifecycle.test.ts b/apps/web/lib/plugins/registry-provider-lifecycle.test.ts
index c23c1e2cbe..afc4726b51 100644
--- a/apps/web/lib/plugins/registry-provider-lifecycle.test.ts
+++ b/apps/web/lib/plugins/registry-provider-lifecycle.test.ts
@@ -119,6 +119,70 @@ describe("pluginRegistry — repository provider result lifecycle", () => {
});
});
+describe("pluginRegistry — atomic unload and work lifecycle", () => {
+ it("does not abort in-flight provider work when an atomic unload rolls back", async () => {
+ let release!: () => void;
+ const gate = new Promise((resolve) => {
+ release = resolve;
+ });
+ const provider = repositoryProvider({
+ listRepositories: ({ signal }) =>
+ new Promise((resolve, reject) => {
+ signal.addEventListener(
+ "abort",
+ () => reject(new DOMException("aborted", "AbortError")),
+ { once: true },
+ );
+ gate.then(() => resolve([]));
+ }),
+ });
+ pluginRegistry.forPlugin(PRIMARY_PLUGIN_ID).registerRepositoryProvider(provider);
+ const request = pluginRegistry
+ .getRepositoryProvider(SOURCE_CONTROL_PROVIDER_ID)!
+ .listRepositories({ workspaceId: WORKSPACE_ID, signal: new AbortController().signal });
+ await Promise.resolve();
+
+ expect(() =>
+ pluginRegistry.runAtomicMutation(() => {
+ pluginRegistry.unregisterPlugin(PRIMARY_PLUGIN_ID);
+ throw new Error("staged commit failed");
+ }),
+ ).toThrow("staged commit failed");
+
+ release();
+ await expect(request).resolves.toEqual([]);
+ });
+
+ it("aborts in-flight provider work once an atomic unload commits", async () => {
+ const aborted = vi.fn();
+ const provider = repositoryProvider({
+ listRepositories: ({ signal }) =>
+ new Promise((_, reject) => {
+ signal.addEventListener(
+ "abort",
+ () => {
+ aborted();
+ reject(new DOMException("aborted", "AbortError"));
+ },
+ { once: true },
+ );
+ }),
+ });
+ pluginRegistry.forPlugin(PRIMARY_PLUGIN_ID).registerRepositoryProvider(provider);
+ const request = pluginRegistry
+ .getRepositoryProvider(SOURCE_CONTROL_PROVIDER_ID)!
+ .listRepositories({ workspaceId: WORKSPACE_ID, signal: new AbortController().signal });
+ await Promise.resolve();
+
+ pluginRegistry.runAtomicMutation(() => {
+ pluginRegistry.unregisterPlugin(PRIMARY_PLUGIN_ID);
+ });
+
+ await expect(request).rejects.toMatchObject({ name: "AbortError" });
+ expect(aborted).toHaveBeenCalledOnce();
+ });
+});
+
describe("pluginRegistry — repository provider reload lifecycle", () => {
it("keeps re-enabled provider work tracked after an older request settles", async () => {
let rejectFirst!: (error: Error) => void;
diff --git a/apps/web/lib/plugins/registry-provider-ownership.ts b/apps/web/lib/plugins/registry-provider-ownership.ts
index 743db477d6..e32dc56779 100644
--- a/apps/web/lib/plugins/registry-provider-ownership.ts
+++ b/apps/web/lib/plugins/registry-provider-ownership.ts
@@ -1,3 +1,7 @@
+export interface PluginProviderOwnershipSnapshot {
+ owners: Map;
+ declarations: Map>;
+}
const PROVIDER_ID_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
const CORE_PROVIDER_IDS = new Set(["github", "gitlab", "azure_devops"]);
@@ -10,6 +14,31 @@ export class PluginProviderOwnership {
this.declarations.set(pluginId, new Set(ids));
}
+ clearDeclarations(pluginId: string): void {
+ this.declarations.delete(pluginId);
+ }
+
+ getDeclarations(pluginId: string): string[] | undefined {
+ const ids = this.declarations.get(pluginId);
+ return ids ? [...ids] : undefined;
+ }
+
+ snapshot(): PluginProviderOwnershipSnapshot {
+ return {
+ owners: new Map(this.owners),
+ declarations: new Map(
+ [...this.declarations].map(([pluginId, ids]) => [pluginId, new Set(ids)]),
+ ),
+ };
+ }
+
+ restore(snapshot: PluginProviderOwnershipSnapshot): void {
+ this.owners = new Map(snapshot.owners);
+ this.declarations = new Map(
+ [...snapshot.declarations].map(([pluginId, ids]) => [pluginId, new Set(ids)]),
+ );
+ }
+
claim(pluginId: string, providerId: string): void {
if (!PROVIDER_ID_PATTERN.test(providerId)) {
throw new Error(
diff --git a/apps/web/lib/plugins/registry.test.ts b/apps/web/lib/plugins/registry.test.ts
index cebec11c12..3c5d42ffa7 100644
--- a/apps/web/lib/plugins/registry.test.ts
+++ b/apps/web/lib/plugins/registry.test.ts
@@ -80,6 +80,26 @@ describe("pluginRegistry", () => {
}
});
+ it("rolls back translations and registrations when a staged atomic commit throws", () => {
+ const scoped = pluginRegistry.forPlugin("plugin-a");
+ scoped.registerTranslations({ en: { greeting: "Hello" } });
+ scoped.registerNavItem({ id: "nav-rollback", label: "A", path: "/rollback" });
+ expect(i18n.getResourceBundle("en", "plugin-plugin-a")?.greeting).toBe("Hello");
+
+ expect(() =>
+ pluginRegistry.runAtomicMutation(() => {
+ pluginRegistry.unregisterPlugin("plugin-a");
+ scoped.registerNavItem({ id: "nav-committed", label: "A", path: "/committed" });
+ scoped.registerTranslations({ en: { greeting: "Bye" } });
+ throw new Error("staged commit failed");
+ }),
+ ).toThrow("staged commit failed");
+
+ expect(i18n.getResourceBundle("en", "plugin-plugin-a")?.greeting).toBe("Hello");
+ expect(pluginRegistry.getNavItems().map((item) => item.id)).toContain("nav-rollback");
+ expect(pluginRegistry.getNavItems().map((item) => item.id)).not.toContain("nav-committed");
+ });
+
it("registers and returns a nav item", () => {
const scoped = pluginRegistry.forPlugin("plugin-a");
diff --git a/apps/web/lib/plugins/registry.ts b/apps/web/lib/plugins/registry.ts
index 127e05904f..6597b41321 100644
--- a/apps/web/lib/plugins/registry.ts
+++ b/apps/web/lib/plugins/registry.ts
@@ -1,3 +1,4 @@
+/* eslint-disable max-lines -- The registry intentionally centralizes one atomic contribution state. */
/**
* Reactive singleton `PluginRegistry` (docs/plans/plugins/PLUGIN-API.md).
*
@@ -31,12 +32,21 @@ import type {
import type { ComponentType } from "react";
import { pluginSlotOrderingId, taskActionKey } from "./registry-normalization";
import {
- wrapRepositoryProviderLifecycle,
wrapReviewProviderLifecycle,
+ wrapRepositoryProviderLifecycle,
} from "./registry-provider-lifecycle";
+import {
+ PluginProviderOwnership,
+ type PluginProviderOwnershipSnapshot,
+} from "./registry-provider-ownership";
import { PluginWorkLifecycle } from "./registry-work-lifecycle";
-import { PluginProviderOwnership } from "./registry-provider-ownership";
-import { registerPluginTranslations, unregisterPluginTranslations } from "./plugin-translations";
+import {
+ registerPluginTranslations,
+ restorePluginTranslations,
+ snapshotPluginTranslations,
+ unregisterPluginTranslations,
+ type PluginTranslationsSnapshot,
+} from "./plugin-translations";
import type {
PluginIntegrationSettingsRegistration,
PluginKeybindingHandler,
@@ -73,6 +83,30 @@ interface WsHandlerRegistration {
handler: WsHandler;
}
+type PluginRegistryStateSnapshot = {
+ routes: Owned[];
+ settingsRoutes: Owned[];
+ integrationSettings: Map>;
+ integrationEnabled: Map>;
+ navItems: Owned[];
+ slotComponents: Owned[];
+ wsHandlers: Owned[];
+ keybindingHandlers: Owned[];
+ repositoryProviders: Map>;
+ taskActions: Map>;
+ reviewProviders: Map>;
+ taskPanels: Owned[];
+ taskMenuActions: Owned[];
+ taskFilters: Owned[];
+ taskListFacets: Owned[];
+ nextSlotRegistrationId: number;
+ pluginNames: Map;
+ pluginLifecycles: Map;
+ declaredKeybindingIds: Map>;
+ providerOwnership: PluginProviderOwnershipSnapshot;
+ translations: PluginTranslationsSnapshot;
+};
+
const CORE_INTEGRATION_SETTINGS_IDS = new Set([
"azure-devops",
"github",
@@ -129,6 +163,9 @@ class PluginRegistryStore {
private declaredKeybindingIds = new Map>();
private listeners = new Set<() => void>();
private version = 0;
+ private mutationDepth = 0;
+ private mutationDirty = false;
+ private deferredWorkAborts = new Set();
constructor() {
i18n.on("languageChanged", () => this.notify());
@@ -140,6 +177,89 @@ class PluginRegistryStore {
this.listeners.delete(listener);
};
};
+ runAtomicMutation(operation: () => T): T {
+ const snapshot = this.captureState();
+ const deferredWorkAborts = new Set(this.deferredWorkAborts);
+ const mutationDirty = this.mutationDirty;
+ this.mutationDepth += 1;
+ try {
+ return operation();
+ } catch (error) {
+ this.restoreState(snapshot);
+ this.deferredWorkAborts = deferredWorkAborts;
+ this.mutationDirty = mutationDirty;
+ throw error;
+ } finally {
+ this.mutationDepth -= 1;
+ if (this.mutationDepth === 0) {
+ if (this.mutationDirty) {
+ this.mutationDirty = false;
+ this.version += 1;
+ this.listeners.forEach((listener) => listener());
+ }
+ const deferred = [...this.deferredWorkAborts];
+ this.deferredWorkAborts.clear();
+ // The mutation committed; the registrations the work lifecycle backed
+ // are gone, so their in-flight operations may now be canceled. A
+ // rolled-back mutation clears the queue above so nothing is aborted.
+ deferred.forEach((pluginId) => this.workLifecycle.abort(pluginId));
+ }
+ }
+ }
+
+ private captureState(): PluginRegistryStateSnapshot {
+ return {
+ routes: [...this.routes],
+ settingsRoutes: [...this.settingsRoutes],
+ integrationSettings: new Map(this.integrationSettings),
+ integrationEnabled: new Map(
+ [...this.integrationEnabled].map(([id, values]) => [id, new Map(values)]),
+ ),
+ navItems: [...this.navItems],
+ slotComponents: [...this.slotComponents],
+ wsHandlers: [...this.wsHandlers],
+ keybindingHandlers: [...this.keybindingHandlers],
+ repositoryProviders: new Map(this.repositoryProviders),
+ taskActions: new Map(this.taskActions),
+ reviewProviders: new Map(this.reviewProviders),
+ taskPanels: [...this.taskPanels],
+ taskMenuActions: [...this.taskMenuActions],
+ taskFilters: [...this.taskFilters],
+ taskListFacets: [...this.taskListFacets],
+ nextSlotRegistrationId: this.nextSlotRegistrationId,
+ pluginNames: new Map(this.pluginNames),
+ pluginLifecycles: new Map(this.pluginLifecycles),
+ declaredKeybindingIds: new Map(
+ [...this.declaredKeybindingIds].map(([id, values]) => [id, new Set(values)]),
+ ),
+ providerOwnership: this.providerOwnership.snapshot(),
+ translations: snapshotPluginTranslations(),
+ };
+ }
+
+ private restoreState(snapshot: PluginRegistryStateSnapshot): void {
+ this.routes = snapshot.routes;
+ this.settingsRoutes = snapshot.settingsRoutes;
+ this.integrationSettings = snapshot.integrationSettings;
+ this.integrationEnabled = snapshot.integrationEnabled;
+ this.navItems = snapshot.navItems;
+ this.slotComponents = snapshot.slotComponents;
+ this.wsHandlers = snapshot.wsHandlers;
+ this.keybindingHandlers = snapshot.keybindingHandlers;
+ this.repositoryProviders = snapshot.repositoryProviders;
+ this.taskActions = snapshot.taskActions;
+ this.reviewProviders = snapshot.reviewProviders;
+ this.taskPanels = snapshot.taskPanels;
+ this.taskMenuActions = snapshot.taskMenuActions;
+ this.taskFilters = snapshot.taskFilters;
+ this.taskListFacets = snapshot.taskListFacets;
+ this.nextSlotRegistrationId = snapshot.nextSlotRegistrationId;
+ this.pluginNames = snapshot.pluginNames;
+ this.pluginLifecycles = snapshot.pluginLifecycles;
+ this.declaredKeybindingIds = snapshot.declaredKeybindingIds;
+ this.providerOwnership.restore(snapshot.providerOwnership);
+ restorePluginTranslations(snapshot.translations);
+ }
getVersion = (): number => this.version;
@@ -344,6 +464,19 @@ class PluginRegistryStore {
this.providerOwnership.setDeclarations(pluginId, ids);
}
+ clearDeclaredRepositoryProviderIds(pluginId: string): void {
+ this.providerOwnership.clearDeclarations(pluginId);
+ }
+
+ restorePluginName(pluginId: string, name: string | undefined): void {
+ if (name) this.pluginNames.set(pluginId, name);
+ else this.pluginNames.delete(pluginId);
+ }
+
+ getDeclaredRepositoryProviderIds(pluginId: string): string[] | undefined {
+ return this.providerOwnership.getDeclarations(pluginId);
+ }
+
registerRepositoryProvider(pluginId: string, provider: RepositoryProviderRegistration): void {
this.providerOwnership.claim(pluginId, provider.id);
if (this.repositoryProviders.has(provider.id)) {
@@ -626,6 +759,13 @@ class PluginRegistryStore {
}
private abortPluginWork(pluginId: string): void {
+ if (this.mutationDepth > 0) {
+ // Deferred: an enclosing runAtomicMutation may still throw and roll
+ // registrations back. Aborting now would cancel work the rollback
+ // expects to stay alive. The abort runs only once the mutation commits.
+ this.deferredWorkAborts.add(pluginId);
+ return;
+ }
this.workLifecycle.abort(pluginId);
}
@@ -649,6 +789,10 @@ class PluginRegistryStore {
}
private notify(): void {
+ if (this.mutationDepth > 0) {
+ this.mutationDirty = true;
+ return;
+ }
this.version += 1;
this.listeners.forEach((listener) => listener());
}
diff --git a/apps/web/lib/plugins/sdk-contract.test.ts b/apps/web/lib/plugins/sdk-contract.test.ts
index cb42c49231..26af63b36d 100644
--- a/apps/web/lib/plugins/sdk-contract.test.ts
+++ b/apps/web/lib/plugins/sdk-contract.test.ts
@@ -1,23 +1,45 @@
import { describe, expect, it } from "vitest";
import type {
- PluginHostApi as PublicPluginHostApi,
ChatSubmitDecorationSlotProps as PublicChatSubmitDecorationSlotProps,
+ HostReact as PublicHostReact,
MainTopBarSlotProps as PublicMainTopBarSlotProps,
+ PluginConversationApi as PublicPluginConversationApi,
+ PluginConversationError as PublicPluginConversationError,
+ PluginConversationMessage as PublicPluginConversationMessage,
+ PluginConversationTurn as PublicPluginConversationTurn,
+ PluginHostApi as PublicPluginHostApi,
PluginNavSection as PublicPluginNavSection,
PluginRegistry as PublicPluginRegistry,
+ PluginSessionMessagesQuery as PublicPluginSessionMessagesQuery,
+ PluginSessionMessagesState as PublicPluginSessionMessagesState,
+ PluginSessionTurnsState as PublicPluginSessionTurnsState,
+ PluginTaskPanelContext as PublicPluginTaskPanelContext,
+ PluginTaskPanelProps as PublicPluginTaskPanelProps,
+ PluginUIApi as PublicPluginUIApi,
RepositoryProviderRegistration as PublicRepositoryProviderRegistration,
ReviewSummary as PublicReviewSummary,
ReviewTaskAssociation as PublicReviewTaskAssociation,
+ TaskPanelRegistration as PublicTaskPanelRegistration,
} from "@kandev/plugin-sdk";
import type {
- PluginHostApi,
ChatSubmitDecorationSlotProps as HostChatSubmitDecorationSlotProps,
MainTopBarSlotProps as HostMainTopBarSlotProps,
+ PluginConversationApi,
+ PluginConversationError,
+ PluginConversationMessage,
+ PluginConversationTurn,
+ PluginHostApi,
PluginNavSection,
PluginRegistry,
+ PluginSessionMessagesQuery,
+ PluginSessionMessagesState,
+ PluginSessionTurnsState,
+ PluginTaskPanelContext,
+ PluginTaskPanelProps,
RepositoryProviderRegistration,
ReviewItemSummary,
ReviewTaskAssociation,
+ TaskPanelRegistration,
} from "./types";
type MissingPublicHostKeys = Exclude;
@@ -26,6 +48,15 @@ type MissingHostRegistryKeys = Exclude = Left extends Right ? (Right extends Left ? true : false) : false;
+type HasUseLayoutEffect = "useLayoutEffect" extends keyof PublicHostReact ? true : false;
+type HasPromptMentionText = "PromptMentionText" extends keyof PublicPluginUIApi ? true : false;
+type HasConversationApi = "conversation" extends keyof PublicPluginHostApi ? true : false;
+
+const legacyTaskPanelRegistration: PublicTaskPanelRegistration = {
+ id: "legacy",
+ title: "Legacy",
+ Component: () => null,
+};
function publicHostContract(value: PluginHostApi): PublicPluginHostApi {
return value;
@@ -60,6 +91,43 @@ describe("public plugin SDK", () => {
HostChatSubmitDecorationSlotProps,
PublicChatSubmitDecorationSlotProps
> = true;
+ const conversationMessageIsCanonical: SameType<
+ PluginConversationMessage,
+ PublicPluginConversationMessage
+ > = true;
+ const conversationTurnIsCanonical: SameType<
+ PluginConversationTurn,
+ PublicPluginConversationTurn
+ > = true;
+ const conversationErrorIsCanonical: SameType<
+ PluginConversationError,
+ PublicPluginConversationError
+ > = true;
+ const messagesQueryIsCanonical: SameType<
+ PluginSessionMessagesQuery,
+ PublicPluginSessionMessagesQuery
+ > = true;
+ const messagesStateIsCanonical: SameType<
+ PluginSessionMessagesState,
+ PublicPluginSessionMessagesState
+ > = true;
+ const turnsStateIsCanonical: SameType =
+ true;
+ const conversationApiIsCanonical: SameType =
+ true;
+ const taskPanelContextIsCanonical: SameType<
+ PluginTaskPanelContext,
+ PublicPluginTaskPanelContext
+ > = true;
+ const taskPanelPropsAreCanonical: SameType =
+ true;
+ const taskPanelRegistrationIsCanonical: SameType<
+ TaskPanelRegistration,
+ PublicTaskPanelRegistration
+ > = true;
+ const publicReactHasLayoutEffect: HasUseLayoutEffect = true;
+ const publicUiHasPromptMentionText: HasPromptMentionText = true;
+ const publicHostHasConversation: HasConversationApi = true;
expect(hostHasEveryPublicKey).toBe(true);
expect(registryHasEveryPublicKey).toBe(true);
expect(publicHasEveryRegistryKey).toBe(true);
@@ -71,6 +139,20 @@ describe("public plugin SDK", () => {
expect(navSectionIsCanonical).toBe(true);
expect(mainTopBarSlotPropsAreCanonical).toBe(true);
expect(chatSubmitDecorationSlotPropsAreCanonical).toBe(true);
+ expect(conversationMessageIsCanonical).toBe(true);
+ expect(conversationTurnIsCanonical).toBe(true);
+ expect(conversationErrorIsCanonical).toBe(true);
+ expect(messagesQueryIsCanonical).toBe(true);
+ expect(messagesStateIsCanonical).toBe(true);
+ expect(turnsStateIsCanonical).toBe(true);
+ expect(conversationApiIsCanonical).toBe(true);
+ expect(taskPanelContextIsCanonical).toBe(true);
+ expect(taskPanelPropsAreCanonical).toBe(true);
+ expect(taskPanelRegistrationIsCanonical).toBe(true);
+ expect(publicReactHasLayoutEffect).toBe(true);
+ expect(publicUiHasPromptMentionText).toBe(true);
+ expect(publicHostHasConversation).toBe(true);
+ expect(legacyTaskPanelRegistration.title).toBe("Legacy");
expect(publicHostContract).toBeTypeOf("function");
expect(publicRegistryContract).toBeTypeOf("function");
});
diff --git a/apps/web/lib/plugins/types.ts b/apps/web/lib/plugins/types.ts
index b5b22e592a..782d4fed86 100644
--- a/apps/web/lib/plugins/types.ts
+++ b/apps/web/lib/plugins/types.ts
@@ -266,6 +266,20 @@ export type ReviewProviderRegistration = Parameters<
PluginSDK.PluginRegistry["registerReviewProvider"]
>[0];
+export type PluginConversationAuthor = PluginSDK.PluginConversationAuthor;
+export type PluginConversationSort = PluginSDK.PluginConversationSort;
+export type PluginConversationMessage = PluginSDK.PluginConversationMessage;
+export type PluginConversationTurn = PluginSDK.PluginConversationTurn;
+export type PluginSessionMessagesQuery = PluginSDK.PluginSessionMessagesQuery;
+export type PluginConversationErrorCode = PluginSDK.PluginConversationErrorCode;
+export type PluginConversationError = PluginSDK.PluginConversationError;
+export type PluginSessionMessagesState = PluginSDK.PluginSessionMessagesState;
+export type PluginSessionTurnsState = PluginSDK.PluginSessionTurnsState;
+export type PluginConversationApi = PluginSDK.PluginConversationApi;
+export type PluginOpenMessageResult = PluginSDK.PluginOpenMessageResult;
+export type PluginTaskPanelConversationCapability = PluginSDK.PluginTaskPanelConversationCapability;
+export type PluginTaskPanelContext = PluginSDK.PluginTaskPanelContext;
+export type PluginSessionKind = PluginSDK.PluginSessionKind;
/** Presentation context a task panel or kanban menu action renders under. */
export type PluginPresentation = "desktop" | "mobile";
diff --git a/apps/web/lib/state/app-state-types.ts b/apps/web/lib/state/app-state-types.ts
index 1b97e18190..d6129e4fdd 100644
--- a/apps/web/lib/state/app-state-types.ts
+++ b/apps/web/lib/state/app-state-types.ts
@@ -422,7 +422,12 @@ export type AppState = KanbanSlice & {
/** Upserts a turn row, rejecting stale updates (see shouldApplyTurnUpdate). */
addTurn: (turn: Turn) => void;
/** Merges a complete REST snapshot and reconciles its marker atomically. */
- mergeTurnsSnapshot: (sessionId: string, turns: Turn[], hydrationEpoch: number) => void;
+ mergeTurnsSnapshot: (
+ sessionId: string,
+ turns: Turn[],
+ hydrationEpoch: number,
+ options?: { replace?: boolean },
+ ) => void;
completeTurn: (
sessionId: string,
turnId: string,
diff --git a/apps/web/lib/state/dockview-extra-panel-actions.ts b/apps/web/lib/state/dockview-extra-panel-actions.ts
index a1cf4561f7..1cfc5ee47f 100644
--- a/apps/web/lib/state/dockview-extra-panel-actions.ts
+++ b/apps/web/lib/state/dockview-extra-panel-actions.ts
@@ -27,9 +27,9 @@ let scrollTargetToken = 0;
*/
function buildTranscriptActions(set: StoreSet, get: StoreGet) {
return {
- scrollTranscriptToMessage: (sessionId: string, messageId: string, title: string) => {
+ scrollTranscriptToMessage: (sessionId: string, messageId: string, title: string): boolean => {
const { api: dockviewApi, centerGroupId } = get();
- if (!dockviewApi) return;
+ if (!dockviewApi) return false;
const sessionPanelId = `session:${sessionId}`;
const targetPanel = dockviewApi.getPanel(sessionPanelId) ?? dockviewApi.getPanel("chat");
if (targetPanel) {
@@ -46,6 +46,7 @@ function buildTranscriptActions(set: StoreSet, get: StoreGet) {
hostPanelId: targetPanel?.id ?? sessionPanelId,
},
});
+ return true;
},
clearScrollTarget: (token: number) => {
if (get().scrollTarget?.token === token) set({ scrollTarget: null });
diff --git a/apps/web/lib/state/dockview-panel-actions.prompt-history-panel.test.ts b/apps/web/lib/state/dockview-panel-actions.prompt-history-panel.test.ts
index 6927bf7de0..da06f8e0ca 100644
--- a/apps/web/lib/state/dockview-panel-actions.prompt-history-panel.test.ts
+++ b/apps/web/lib/state/dockview-panel-actions.prompt-history-panel.test.ts
@@ -77,7 +77,7 @@ describe("scrollTranscriptToMessage", () => {
const store = makeStore(api);
const actions = buildExtraPanelActions(store.set, store.get);
- actions.scrollTranscriptToMessage(SESSION_ID, MESSAGE_ID, "Agent");
+ const queued = actions.scrollTranscriptToMessage(SESSION_ID, MESSAGE_ID, "Agent");
expect(api.getPanel(`session:${SESSION_ID}`)).toMatchObject({ api: { component: "chat" } });
expect(store.state.scrollTarget).toMatchObject({
@@ -85,6 +85,18 @@ describe("scrollTranscriptToMessage", () => {
messageId: MESSAGE_ID,
hostPanelId: `session:${SESSION_ID}`,
});
+ expect(queued).toBe(true);
+ });
+
+ it("reports unavailable when no dockview host can queue navigation", () => {
+ const store = makeStore(makeApi());
+ store.state.api = null;
+ const actions = buildExtraPanelActions(store.set, store.get);
+
+ const queued = actions.scrollTranscriptToMessage(SESSION_ID, MESSAGE_ID, "Agent");
+
+ expect(queued).toBe(false);
+ expect(store.state.scrollTarget).toBeNull();
});
it("focuses an existing session panel instead of adding a second tab", () => {
@@ -125,7 +137,9 @@ describe("scrollTranscriptToMessage", () => {
expect((api.getPanel("chat") as unknown as { isActive: boolean }).isActive).toBe(true);
expect(store.state.scrollTarget?.hostPanelId).toBe("chat");
});
+});
+describe("scrollTranscriptToMessage target lifecycle", () => {
it("activates the target panel before recording the target", () => {
const api = makeApi();
api.addPanel({
diff --git a/apps/web/lib/state/dockview-store.ts b/apps/web/lib/state/dockview-store.ts
index c34b25c720..a5a2216112 100644
--- a/apps/web/lib/state/dockview-store.ts
+++ b/apps/web/lib/state/dockview-store.ts
@@ -271,7 +271,7 @@ type DockviewStore = {
selectedDiff: { path: string; content?: string } | null;
setSelectedDiff: (diff: { path: string; content?: string } | null) => void;
scrollTarget: TranscriptScrollTarget | null;
- scrollTranscriptToMessage: (sessionId: string, messageId: string, title: string) => void;
+ scrollTranscriptToMessage: (sessionId: string, messageId: string, title: string) => boolean;
clearScrollTarget: (token: number) => void;
clearScrollTargetForOwner: (sessionId: string, hostPanelId: string) => void;
activeGroupId: string | null;
diff --git a/apps/web/lib/state/layout-manager/panel-title.ts b/apps/web/lib/state/layout-manager/panel-title.ts
index 0e9a3e6f64..b791c4a99d 100644
--- a/apps/web/lib/state/layout-manager/panel-title.ts
+++ b/apps/web/lib/state/layout-manager/panel-title.ts
@@ -1,6 +1,7 @@
import { t } from "@/lib/i18n";
import { panelRegistryEntry } from "./constants";
+import { resolvePluginPanelDefinition } from "./plugin-panels";
/**
* The display title for a registry panel, in the active locale.
@@ -24,6 +25,8 @@ import { panelRegistryEntry } from "./constants";
* `panelFromDockviewPanel` canonicalizes on the way back out.
*/
export function panelTitle(id: string, fallback?: string, component?: string): string {
+ const pluginPanel = resolvePluginPanelDefinition(id);
+ if (pluginPanel) return pluginPanel.title;
const config = panelRegistryEntry(id, component);
if (!config) return fallback ?? id;
return config.titleKey ? t(config.titleKey) : config.title;
diff --git a/apps/web/lib/state/layout-manager/plugin-panels.test.ts b/apps/web/lib/state/layout-manager/plugin-panels.test.ts
index 59a8131221..e3dfa2136e 100644
--- a/apps/web/lib/state/layout-manager/plugin-panels.test.ts
+++ b/apps/web/lib/state/layout-manager/plugin-panels.test.ts
@@ -1,4 +1,5 @@
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { i18n as I18n } from "i18next";
import { pluginRegistry } from "@/lib/plugins/registry";
import {
isKnownPanelId,
@@ -6,6 +7,7 @@ import {
parsePluginPanelId,
pluginPanelId,
resolvePluginPanelDefinition,
+ resolveTaskPanelTitle,
} from "./plugin-panels";
afterEach(() => {
@@ -91,3 +93,30 @@ describe("resolvePluginPanelDefinition", () => {
expect(resolvePluginPanelDefinition("chat")).toBeUndefined();
});
});
+
+describe("resolveTaskPanelTitle", () => {
+ it("uses the plugin namespace and falls back to the canonical English title", () => {
+ function Notes() {
+ return null;
+ }
+ pluginRegistry.forPlugin("plugin-a").registerTaskPanel({
+ id: "notes",
+ title: "Notes",
+ titleKey: "panels.notes",
+ Component: Notes,
+ });
+ const registration = pluginRegistry.getTaskPanel("plugin-a", "notes");
+ if (!registration) throw new Error("panel registration missing");
+ const translate = vi.fn(() => "Notas");
+
+ expect(
+ resolveTaskPanelTitle(registration, {
+ t: translate as unknown as I18n["t"],
+ }),
+ ).toBe("Notas");
+ expect(translate).toHaveBeenCalledWith("panels.notes", {
+ ns: "plugin-plugin-a",
+ defaultValue: "Notes",
+ });
+ });
+});
diff --git a/apps/web/lib/state/layout-manager/plugin-panels.ts b/apps/web/lib/state/layout-manager/plugin-panels.ts
index 3247c54f7d..58d9fb3c1b 100644
--- a/apps/web/lib/state/layout-manager/plugin-panels.ts
+++ b/apps/web/lib/state/layout-manager/plugin-panels.ts
@@ -7,6 +7,10 @@
* (rather than one per plugin) and lets a saved layout round-trip even when
* the plugin that registered the panel is no longer installed.
*/
+import type { i18n as I18n } from "i18next";
+import { i18n } from "@/lib/i18n";
+import { pluginTranslationNamespace } from "@/lib/plugins/plugin-translations";
+import type { PluginTaskPanelRegistration } from "@/lib/plugins/registry-registration-types";
import { pluginRegistry } from "@/lib/plugins/registry";
import { KNOWN_PANEL_IDS, STRUCTURAL_COMPONENTS } from "./constants";
import type { LayoutPanel } from "./types";
@@ -60,6 +64,23 @@ export function isStructuralComponent(component: string): boolean {
return STRUCTURAL_COMPONENTS.has(component) || component === PLUGIN_PANEL_COMPONENT;
}
+/** Resolves plugin-owned copy in its generation namespace with a saved-layout-safe fallback. */
+export function resolveTaskPanelTitle(
+ registration: PluginTaskPanelRegistration,
+ translator: Pick = i18n,
+): string {
+ if (!registration.titleKey) return registration.title;
+ return translator.t(registration.titleKey, {
+ ns: pluginTranslationNamespace(registration.pluginId),
+ defaultValue: registration.title,
+ });
+}
+export function canonicalPluginPanelTitle(id: string): string | undefined {
+ const parsed = parsePluginPanelId(id);
+ if (!parsed) return undefined;
+ return pluginRegistry.getTaskPanel(parsed.pluginId, parsed.panelKey)?.title;
+}
+
/**
* Resolves a `plugin::` id to a full `LayoutPanel`
* definition using the plugin's current registration (title/icon), or
@@ -74,7 +95,7 @@ export function resolvePluginPanelDefinition(id: string): LayoutPanel | undefine
return {
id,
component: PLUGIN_PANEL_COMPONENT,
- title: registration.title,
+ title: resolveTaskPanelTitle(registration),
tabComponent: PLUGIN_PANEL_TAB_COMPONENT,
params: { pluginId: parsed.pluginId, panelKey: parsed.panelKey },
};
diff --git a/apps/web/lib/state/layout-manager/serializer.ts b/apps/web/lib/state/layout-manager/serializer.ts
index 26c7c36cc6..05250181c7 100644
--- a/apps/web/lib/state/layout-manager/serializer.ts
+++ b/apps/web/lib/state/layout-manager/serializer.ts
@@ -20,6 +20,7 @@ import {
RIGHT_BOTTOM_GROUP,
} from "./constants";
import { panelTitle } from "./panel-title";
+import { canonicalPluginPanelTitle } from "./plugin-panels";
/** Canonical English, because `normalizePanel` produces a stored LayoutState. */
// i18n-exempt: canonical English persisted in saved layouts, compared when restoring.
@@ -227,7 +228,11 @@ function panelFromDockviewPanel(panel: any): LayoutPanel {
component: panel.view?.contentComponent ?? panel.id,
// CAPTURE direction: dockview holds the localized title, and this result is
// what gets persisted, so a registry panel goes back to canonical English.
- title: canonicalPanelTitle(panel.id, panel.view?.contentComponent) ?? panel.title ?? panel.id,
+ title:
+ canonicalPluginPanelTitle(panel.id) ??
+ canonicalPanelTitle(panel.id, panel.view?.contentComponent) ??
+ panel.title ??
+ panel.id,
...(panel.view?.tabComponent ? { tabComponent: panel.view.tabComponent } : {}),
...(panel.params ? { params: panel.params as Record } : {}),
};
diff --git a/apps/web/lib/state/slices/session/turn-actions.test.ts b/apps/web/lib/state/slices/session/turn-actions.test.ts
index a45b608ebd..f00a72249b 100644
--- a/apps/web/lib/state/slices/session/turn-actions.test.ts
+++ b/apps/web/lib/state/slices/session/turn-actions.test.ts
@@ -1,3 +1,4 @@
+/* eslint-disable max-lines -- Turn reconciliation fixtures cover the store contract in one file. */
import { describe, expect, it } from "vitest";
import { create } from "zustand";
import { immer } from "zustand/middleware/immer";
@@ -283,6 +284,30 @@ describe("mergeTurnsSnapshot", () => {
expect(store.getState().turns.loadedBySession[SESSION_ID]).toBe(true);
expect(store.getState().turns.activeBySession[SESSION_ID]).toBe("turn-new");
});
+
+ it("replaces rows missing from an authoritative recovery snapshot", () => {
+ const store = makeStore();
+ seedSession(store, "RUNNING", LATER_AT);
+ store.getState().addTurn(turn("turn-stale", { started_at: STARTED_AT }));
+ store.getState().addTurn(turn("turn-kept", { started_at: LATER_AT }));
+ store.getState().setActiveTurn(SESSION_ID, "turn-kept");
+
+ store.getState().mergeTurnsSnapshot(
+ SESSION_ID,
+ [
+ turn("turn-kept", {
+ started_at: LATER_AT,
+ updated_at: LATER_AT,
+ completed_at: COMPLETED_AT,
+ }),
+ ],
+ 0,
+ { replace: true },
+ );
+
+ expect(store.getState().turns.bySession[SESSION_ID].map(({ id }) => id)).toEqual(["turn-kept"]);
+ expect(store.getState().turns.activeBySession[SESSION_ID]).toBeNull();
+ });
});
describe("addTurn malformed timestamps", () => {
diff --git a/apps/web/lib/state/slices/session/turn-actions.ts b/apps/web/lib/state/slices/session/turn-actions.ts
index 83f6cae0ae..5eefdf0072 100644
--- a/apps/web/lib/state/slices/session/turn-actions.ts
+++ b/apps/web/lib/state/slices/session/turn-actions.ts
@@ -168,6 +168,19 @@ export function mergeTurnRows(target: Draft