@antelopejs/dms-ai 0.2.1 → 0.3.0

package/README.md

@@ -17,7 +17,7 @@ Codex is selectable once its CLI is installed.
 
 ## Installation
 
-Add the module to a project that already uses `@antelopejs/dms`:
+Add the module to a project that already uses `@antelopejs/dms` 0.9 (with `@antelopejs/interface-dms` 0.7 and `@antelopejs/dms-frontend` 0.6: the views read their data with its `useApiData`, and the module's routes under `/ai/**` reach the backend through the frontend server, which the module declares as a backend prefix with the session):
 
 ```bash
 ajs project modules add @antelopejs/dms-ai

package/dist/constants/frontend-module.d.ts

@@ -1,3 +1,5 @@
+import type { FrontendBackendProxy } from "@antelopejs/interface-dms/page";
 export declare const FRONTEND_MODULE_NAME = "@antelopejs/dms-ai-frontend-vue";
 export declare const FRONTEND_MODULE_DIR = "../frontend-vue";
 export declare const FRONTEND_MODULE_PRIORITY = 100;
+export declare const FRONTEND_BACKEND_PROXY: FrontendBackendProxy;

package/dist/constants/frontend-module.js

@@ -1,7 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FRONTEND_MODULE_PRIORITY = exports.FRONTEND_MODULE_DIR = exports.FRONTEND_MODULE_NAME = void 0;
+exports.FRONTEND_BACKEND_PROXY = exports.FRONTEND_MODULE_PRIORITY = exports.FRONTEND_MODULE_DIR = exports.FRONTEND_MODULE_NAME = void 0;
+const module_1 = require("./module");
 exports.FRONTEND_MODULE_NAME = "@antelopejs/dms-ai-frontend-vue";
 exports.FRONTEND_MODULE_DIR = "../frontend-vue";
 exports.FRONTEND_MODULE_PRIORITY = 100;
+exports.FRONTEND_BACKEND_PROXY = {
+    path: `${module_1.ROUTE_PREFIX}/**`,
+    auth: "session",
+};
 //# sourceMappingURL=frontend-module.js.map

package/dist/constants/frontend-module.js.map

@@ -1 +1 @@
-{"version":3,"file":"frontend-module.js","sourceRoot":"","sources":["../../src/constants/frontend-module.ts"],"names":[],"mappings":";;;AAAa,QAAA,oBAAoB,GAAG,iCAAiC,CAAC;AACzD,QAAA,mBAAmB,GAAG,iBAAiB,CAAC;AACxC,QAAA,wBAAwB,GAAG,GAAG,CAAC"}
+{"version":3,"file":"frontend-module.js","sourceRoot":"","sources":["../../src/constants/frontend-module.ts"],"names":[],"mappings":";;;AACA,qCAAwC;AAE3B,QAAA,oBAAoB,GAAG,iCAAiC,CAAC;AACzD,QAAA,mBAAmB,GAAG,iBAAiB,CAAC;AACxC,QAAA,wBAAwB,GAAG,GAAG,CAAC;AAO/B,QAAA,sBAAsB,GAAyB;IAC1D,IAAI,EAAE,GAAG,qBAAY,KAAK;IAC1B,IAAI,EAAE,SAAS;CAChB,CAAC"}

package/dist/index.js

@@ -30,6 +30,7 @@ async function start() {
         sourcePath: node_path_1.default.join(__dirname, frontend_module_1.FRONTEND_MODULE_DIR),
         renderer: { name: "vue", version: "3" },
         priority: frontend_module_1.FRONTEND_MODULE_PRIORITY,
+        backendProxies: [frontend_module_1.FRONTEND_BACKEND_PROXY],
     });
     const [moduleRoots, skillDirs, builderEnabled] = await Promise.all([
         (0, module_roots_1.collectModuleRoots)(),

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;AAmBA,8BAEC;AAED,sBAyBC;AAOD,0BAEC;AAzDD,0DAA6B;AAC7B,gEAA6D;AAC7D,yDAAmE;AACnE,iDAAwD;AACxD,kDAAsD;AACtD,qCAA6D;AAC7D,iEAIqC;AACrC,iDAAyD;AACzD,2DAA8D;AAC9D,6DAAgE;AAChE,6DAAyD;AACzD,qDAAuD;AACvD,mBAAiB;AACjB,oBAAkB;AAElB,SAAgB,SAAS,CAAC,MAAe;IACvC,IAAA,kBAAS,EAAC,IAAA,oBAAW,EAAC,MAAM,CAAC,CAAC,CAAC;AACjC,CAAC;AAEM,KAAK,UAAU,KAAK;IACzB,IAAA,4BAAe,GAAE,CAAC;IAClB,MAAM,IAAA,wBAAiB,EAAC;QACtB,IAAI,EAAE,sCAAoB;QAC1B,UAAU,EAAE,mBAAI,CAAC,IAAI,CAAC,SAAS,EAAE,qCAAmB,CAAC;QACrD,QAAQ,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE;QACvC,QAAQ,EAAE,0CAAwB;KACnC,CAAC,CAAC;IAIH,MAAM,CAAC,WAAW,EAAE,SAAS,EAAE,cAAc,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACjE,IAAA,iCAAkB,GAAE;QACpB,IAAA,mCAAmB,GAAE;QACrB,IAAA,6BAAkB,GAAE;KACrB,CAAC,CAAC;IACH,KAAK,IAAA,4BAAY,EAAC;QAChB,eAAe,EAAE,OAAO,CAAC,GAAG,EAAE;QAC9B,GAAG,IAAA,kBAAS,GAAE;QACd,WAAW;QACX,SAAS;QACT,cAAc;KACf,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QACf,iBAAO,CAAC,KAAK,CAAC,GAAG,4BAAkB,gBAAgB,EAAE,GAAG,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;AACL,CAAC;AAOD,SAAgB,OAAO;IACrB,IAAA,0BAAe,GAAE,CAAC;AACpB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;AAoBA,8BAEC;AAED,sBA0BC;AAOD,0BAEC;AA3DD,0DAA6B;AAC7B,gEAA6D;AAC7D,yDAAmE;AACnE,iDAAwD;AACxD,kDAAsD;AACtD,qCAA6D;AAC7D,iEAKqC;AACrC,iDAAyD;AACzD,2DAA8D;AAC9D,6DAAgE;AAChE,6DAAyD;AACzD,qDAAuD;AACvD,mBAAiB;AACjB,oBAAkB;AAElB,SAAgB,SAAS,CAAC,MAAe;IACvC,IAAA,kBAAS,EAAC,IAAA,oBAAW,EAAC,MAAM,CAAC,CAAC,CAAC;AACjC,CAAC;AAEM,KAAK,UAAU,KAAK;IACzB,IAAA,4BAAe,GAAE,CAAC;IAClB,MAAM,IAAA,wBAAiB,EAAC;QACtB,IAAI,EAAE,sCAAoB;QAC1B,UAAU,EAAE,mBAAI,CAAC,IAAI,CAAC,SAAS,EAAE,qCAAmB,CAAC;QACrD,QAAQ,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE;QACvC,QAAQ,EAAE,0CAAwB;QAClC,cAAc,EAAE,CAAC,wCAAsB,CAAC;KACzC,CAAC,CAAC;IAIH,MAAM,CAAC,WAAW,EAAE,SAAS,EAAE,cAAc,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACjE,IAAA,iCAAkB,GAAE;QACpB,IAAA,mCAAmB,GAAE;QACrB,IAAA,6BAAkB,GAAE;KACrB,CAAC,CAAC;IACH,KAAK,IAAA,4BAAY,EAAC;QAChB,eAAe,EAAE,OAAO,CAAC,GAAG,EAAE;QAC9B,GAAG,IAAA,kBAAS,GAAE;QACd,WAAW;QACX,SAAS;QACT,cAAc;KACf,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QACf,iBAAO,CAAC,KAAK,CAAC,GAAG,4BAAkB,gBAAgB,EAAE,GAAG,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;AACL,CAAC;AAOD,SAAgB,OAAO;IACrB,IAAA,0BAAe,GAAE,CAAC;AACpB,CAAC"}

package/frontend-vue/app/components/ActivityDetail.vue

@@ -1,11 +1,11 @@
 <script setup lang="ts">
-import { computed, ref, watch } from "vue";
+import { computed, ref } from "vue";
 import DecisionLabel from "../views/DecisionLabel.vue";
 import DiffView from "../views/DiffView.vue";
 import RowStepper from "../views/RowStepper.vue";
 import ResultPill from "../views/ResultPill.vue";
 import UnavailableState from "../views/UnavailableState.vue";
-import { useAiRequest } from "../views/composables/useAiRequest";
+import { useAiData } from "../views/composables/useAiData";
 import { useAssistant } from "../views/composables/useAssistant";
 import { useViewFormat } from "../views/composables/useViewFormat";
 import { AI_PAGES, AI_ROUTES, CHANGE_SET_QUERY_KEY } from "../views/constants";
@@ -30,29 +30,27 @@ interface Props {
 const props = defineProps<Props>();
 
 const { t } = useI18n();
-const { $authFetch } = useAuthFetch();
 const { moment, toolLabel, clock } = useViewFormat();
 const assistant = useAssistant();
-const detail = useAiRequest<ActivityDetailPayload>();
 const isRawShown = ref(false);
 
 const OUTPUT_MAX_LINES = 14;
 const RAW_MAX_LINES = 20;
 
 const rowId = computed(() => props.rowData?.id ?? props.rowData?._id);
+// Read with the page: a deep link (`?record=<id>`) renders the entry on the
+// server and hands it over. The drawer opened again shows the entry read
+// before and reads it again, as a pending call may have ended since.
+const detail = useAiData<ActivityDetailPayload>(() =>
+	rowId.value
+		? `${AI_ROUTES.activity}/${encodeURIComponent(rowId.value)}`
+		: null,
+);
 
 function load(): void {
-	const id = rowId.value;
-	if (!id) return;
-	void detail.run(() =>
-		$authFetch<ActivityDetailPayload>(
-			`${AI_ROUTES.activity}/${encodeURIComponent(id)}`,
-		),
-	);
+	void detail.refresh();
 }
 
-watch(rowId, load, { immediate: true });
-
 const row = computed(() => props.rowData);
 const eyebrow = computed(() => {
 	const current = row.value;

package/frontend-vue/app/components/ChangesView.vue

@@ -1,9 +1,9 @@
 <script setup lang="ts">
-import { computed, onMounted, ref, watch } from "vue";
+import { computed, ref, watch } from "vue";
 import { useDmsRoute } from "#dms/frontend-module";
 import ChangeSetPanel from "../views/ChangeSetPanel.vue";
 import UnavailableState from "../views/UnavailableState.vue";
-import { useAiRequest } from "../views/composables/useAiRequest";
+import { useAiData, useAiPagedData } from "../views/composables/useAiData";
 import { useAssistant } from "../views/composables/useAssistant";
 import { useViewFormat } from "../views/composables/useViewFormat";
 import {
@@ -20,34 +20,18 @@ import type {
 import {
 	changeSetIcon,
 	matchesSearch,
-	readSelectedSet,
 	writeSelectedSet,
 } from "../views/utils/change-sets";
 
 type ScopeFilter = ScopeId | "all";
 
 const { t } = useI18n();
-const { $authFetch } = useAuthFetch();
 const { moment } = useViewFormat();
 const assistant = useAssistant();
 const route = useDmsRoute();
 
-const list = useAiRequest<ListPayload<ChangeSetSummary>>();
-const status = useAiRequest<AssistantStatus>();
-const changeSets = ref<ChangeSetSummary[]>([]);
-const total = ref(0);
 const scope = ref<ScopeFilter>("all");
 const search = ref("");
-const selectedId = ref<string | undefined>(readSelectedSet());
-// The list loads on the client only: until its first answer the server and
-// the hydrating client both draw the skeleton, never a premature empty state.
-const hasLoaded = ref(false);
-
-const SCOPE_ITEMS = computed(() => [
-	{ value: "all", label: t("dms_ai.views.changes.filter_all") },
-	{ value: "safe", label: t("dms_ai.views.changes.filter_safe") },
-	{ value: "vibe", label: t("dms_ai.views.changes.filter_code") },
-]);
 
 function listQuery(offset: number): Record<string, string | number> {
 	const query: Record<string, string | number> = {
@@ -58,46 +42,69 @@ function listQuery(offset: number): Record<string, string | number> {
 	return { ...query, scope: scope.value, filter_scope: `is:${scope.value}` };
 }
 
-async function loadPage(offset: number): Promise<void> {
-	const page = await list.run(() =>
-		$authFetch<ListPayload<ChangeSetSummary>>(AI_ROUTES.changes, {
-			query: listQuery(offset),
+type ChangesPage = ListPayload<ChangeSetSummary>;
+
+/** The sets the pages hold, in order. */
+function loadedCount(pages: ChangesPage[]): number {
+	return pages.reduce((count, page) => count + page.results.length, 0);
+}
+
+// The status and the list's first page are read with the page: a server
+// render shows them, and the selected set's panel, at once. "Load more"
+// appends a page under the scope's key; the page's refreshes read every
+// page loaded again.
+const status = useAiData<AssistantStatus>(AI_ROUTES.status);
+const list = useAiPagedData<ChangesPage, number>(
+	() => `dms-ai:changes:${scope.value}`,
+	({ $authFetch, cursor, signal }) =>
+		$authFetch<ChangesPage>(AI_ROUTES.changes, {
+			query: listQuery(cursor ?? 0),
+			signal,
 		}),
-	);
-	hasLoaded.value = true;
-	if (!page) return;
-	changeSets.value =
-		offset === 0 ? page.results : [...changeSets.value, ...page.results];
-	total.value = page.total;
-	if (selectedId.value === undefined) selectedId.value = page.results[0]?.id;
+	{
+		nextCursor: (page, pages) => {
+			const loaded = loadedCount(pages);
+			return page.results.length > 0 && loaded < page.total ? loaded : null;
+		},
+	},
+);
+const changeSets = computed(() =>
+	list.pages.value.flatMap((page) => page.results),
+);
+const total = computed(() => list.pages.value.at(-1)?.total ?? 0);
+
+function selectedFromRoute(): string | undefined {
+	const id = route.query[CHANGE_SET_QUERY_KEY];
+	return typeof id === "string" && id ? id : undefined;
 }
 
+/** The set picked here or named by the URL (`?set=`); the first one until then. */
+const pickedId = ref<string | undefined>(selectedFromRoute());
+const selectedId = computed(() => pickedId.value ?? changeSets.value[0]?.id);
+
+const SCOPE_ITEMS = computed(() => [
+	{ value: "all", label: t("dms_ai.views.changes.filter_all") },
+	{ value: "safe", label: t("dms_ai.views.changes.filter_safe") },
+	{ value: "vibe", label: t("dms_ai.views.changes.filter_code") },
+]);
+
 function reload(): Promise<void> {
-	return loadPage(0);
+	return list.refresh();
 }
 
+/** Appends the next page; a failure keeps the sets listed and the button. */
 function loadMore(): Promise<void> {
-	return loadPage(changeSets.value.length);
+	return list.loadMore();
 }
 
-onMounted(() => {
-	void status.run(() => $authFetch<AssistantStatus>(AI_ROUTES.status));
-	void reload();
+watch(selectedFromRoute, (id) => {
+	if (id) pickedId.value = id;
 });
 
-watch(scope, reload);
-
-watch(
-	() => route.query[CHANGE_SET_QUERY_KEY],
-	(id) => {
-		if (id) selectedId.value = id;
-	},
-);
-
 function select(id: string | number | undefined): void {
 	if (id === undefined) return;
-	selectedId.value = String(id);
-	writeSelectedSet(selectedId.value);
+	pickedId.value = String(id);
+	writeSelectedSet(pickedId.value);
 }
 
 function sublabel(set: ChangeSetSummary): string {
@@ -134,9 +141,10 @@ const isCheckpointOff = computed(
 );
 const isFirstLoad = computed(
 	() =>
-		(!hasLoaded.value || list.isLoading.value) && changeSets.value.length === 0,
+		changeSets.value.length === 0 &&
+		(list.pending.value || list.status.value === "idle"),
 );
-const hasMore = computed(() => changeSets.value.length < total.value);
+const hasMore = computed(() => list.hasMore.value);
 const listLabel = computed(() =>
 	t("dms_ai.views.changes.list_label", { count: total.value }),
 );
@@ -230,7 +238,6 @@ const emptyActions = computed(() =>
 					v-if="selectedId"
 					:key="selectedId"
 					:change-set-id="selectedId"
-					@changed="reload"
 				/>
 			</DmsMasterDetail>
 			<div v-if="hasMore" class="flex lg:w-[380px] lg:justify-center">
@@ -239,7 +246,7 @@ const emptyActions = computed(() =>
 					variant="outline"
 					size="sm"
 					icon="i-ph-caret-down"
-					:loading="list.isLoading.value"
+					:loading="list.loadingMore.value"
 					:label="t('dms_ai.views.common.load_more')"
 					@click="loadMore"
 				/>

package/frontend-vue/app/plugins/ai.client.ts

@@ -70,6 +70,7 @@ import { runWhenLoggedIn } from "../runtime/session-gate";
 import { installToggleShortcut } from "../runtime/shortcuts";
 import {
 	createSidecarStatusController,
+	type SidecarInfoPayload,
 	type SidecarStatus,
 	type SidecarStatusController,
 } from "../runtime/sidecar-status";
@@ -395,8 +396,13 @@ function createRuntime(
 	const holds = createStreamHolds();
 	const sidecarStatus = followSidecarStatus(controller, client);
 	const activity = createAssistantActivity({
-		fetchStatus: () =>
-			deps.$authFetch(STATUS_PATH) as Promise<AssistantStatusPayload>,
+		// The application's read: polled for as long as the app runs, while
+		// the interval says so.
+		readStatus: (interval) =>
+			useApiData<AssistantStatusPayload>(STATUS_PATH, {
+				refreshInterval: interval,
+				refreshOnPageRefresh: false,
+			}),
 		chat: chat.transport,
 		shouldPoll: () =>
 			!panel.isOpen.value ||
@@ -413,7 +419,6 @@ function createRuntime(
 		activity,
 		currentPage,
 	});
-	void activity.refresh();
 	const stops = [
 		installToggleShortcut({ onToggle: panel.toggle }),
 		followPanel({ panel, activity, holds }, client),
@@ -462,8 +467,13 @@ async function startAssistant(
 		devReload: useDevReload(),
 		router: useDmsRouter(),
 	};
-	const controller = createSidecarStatusController(() =>
-		deps.$authFetch(SIDECAR_INFO_PATH),
+	// Read once the gate opens, then polled while the sidecar comes back.
+	const controller = createSidecarStatusController((interval) =>
+		useApiData<SidecarInfoPayload>(SIDECAR_INFO_PATH, {
+			immediate: false,
+			refreshInterval: interval,
+			refreshOnPageRefresh: false,
+		}),
 	);
 	if (!(await controller.init())) {
 		context.runWithContext(() => unregisterSidePanel(SIDE_PANEL_ID));
@@ -496,7 +506,7 @@ export default defineDmsPlugin((context) => {
 	const appMounted = new Promise<void>((resolve) =>
 		context.hook("app:mounted", resolve),
 	);
-	const { loggedIn } = useUserSession();
+	const { loggedIn } = useDmsUserSession();
 	const stopGate = runWhenLoggedIn(
 		() => loggedIn.value,
 		() =>

package/frontend-vue/app/runtime/assistant-activity.ts

@@ -1,4 +1,4 @@
-import { computed, type ComputedRef, type Ref, ref } from "vue";
+import { computed, type ComputedRef, type Ref, ref, watch } from "vue";
 import type { ChatTransport } from "./chat-transport";
 import { STATUS_POLL_MS } from "./constants";
 import { isTypedMessage } from "./typed-message";
@@ -35,10 +35,24 @@ export interface AssistantActivity {
 	stop: () => void;
 }
 
+/** The read of the backend's status: `useApiData`, polled every `interval`. */
+export interface AssistantStatusRead {
+	data: Readonly<Ref<AssistantStatusPayload | null>>;
+	refresh: () => Promise<void>;
+}
+
+/**
+ * Opens the status read, polled every `interval` ms while it is above 0 and
+ * not polled while it is 0.
+ */
+export type OpenAssistantStatusRead = (
+	interval: () => number,
+) => AssistantStatusRead;
+
 export interface AssistantActivityOptions {
-	fetchStatus: () => Promise<AssistantStatusPayload>;
+	readStatus: OpenAssistantStatusRead;
 	chat: ChatTransport;
-	/** Whether polling is useful now: the tab shows and the panel is closed. */
+	/** Whether polling is useful now: the panel is closed, or its stream is down. */
 	shouldPoll: () => boolean;
 }
 
@@ -55,8 +69,9 @@ function sum(
 
 /**
  * What the tab knows of the assistant's work across chats, from the backend's
- * status (polled while the panel is closed) and from the conversation lists
- * the sidecar broadcasts while the stream is open.
+ * status (polled while the panel is closed or its stream down: the polling
+ * follows `shouldPoll`) and from the conversation lists the sidecar
+ * broadcasts while the stream is open.
  */
 export function createAssistantActivity(
 	options: AssistantActivityOptions,
@@ -65,16 +80,21 @@ export function createAssistantActivity(
 	const workingConversations = ref(0);
 	const lastError = ref<string | null>(null);
 
-	const refresh = async (): Promise<void> => {
-		try {
-			const status = await options.fetchStatus();
-			pendingApprovals.value = status.pendingApprovals ?? 0;
-			workingConversations.value = status.workingConversations ?? 0;
-			lastError.value = status.lastError ?? null;
-		} catch {
-			return;
-		}
-	};
+	const isStopped = ref(false);
+	const status = options.readStatus(() =>
+		!isStopped.value && options.shouldPoll() ? STATUS_POLL_MS : 0,
+	);
+	// A failed read keeps the last answer: the counts stay as they were.
+	const stopFollowing = watch(
+		status.data,
+		(payload) => {
+			if (!payload) return;
+			pendingApprovals.value = payload.pendingApprovals ?? 0;
+			workingConversations.value = payload.workingConversations ?? 0;
+			lastError.value = payload.lastError ?? null;
+		},
+		{ immediate: true },
+	);
 
 	const stopListening = options.chat.onMessage((msg) => {
 		if (!isListFrame(msg)) return;
@@ -85,10 +105,6 @@ export function createAssistantActivity(
 		);
 	});
 
-	const timer = setInterval(() => {
-		if (options.shouldPoll()) void refresh();
-	}, STATUS_POLL_MS);
-
 	return {
 		pendingApprovals,
 		workingConversations,
@@ -96,9 +112,10 @@ export function createAssistantActivity(
 			() => pendingApprovals.value > 0 || workingConversations.value > 0,
 		),
 		lastError,
-		refresh,
+		refresh: () => status.refresh(),
 		stop: () => {
-			clearInterval(timer);
+			isStopped.value = true;
+			stopFollowing();
 			stopListening();
 		},
 	};

package/frontend-vue/app/runtime/sidecar-status.ts

@@ -1,3 +1,4 @@
+import { type Ref, readonly, ref, watch } from "vue";
 import { createBackoff, nextDelay, resetBackoff } from "./backoff";
 import {
 	SIDECAR_POLL_DELAYS_MS,
@@ -38,31 +39,52 @@ export interface SidecarStatusController {
 	dispose: () => void;
 }
 
-export type FetchSidecarInfo = () => Promise<Partial<SidecarInfo>>;
-
-async function fetchInfo(
-	fetchDetails: FetchSidecarInfo,
-): Promise<SidecarInfo | null> {
-	try {
-		const body = await fetchDetails();
-		return {
-			isRunning: body.isRunning === true,
-			hasGivenUp: body.hasGivenUp === true,
-			disabled: body.disabled === true,
-		};
-	} catch {
-		return null;
-	}
+/**
+ * The read of the sidecar's info the controller follows: `useApiData` in the
+ * dashboard, opened with `immediate: false` and polled every `interval`.
+ */
+/** The backend's sidecar info, as far as the tab reads it. */
+export type SidecarInfoPayload = Partial<SidecarInfo>;
+
+export interface SidecarInfoRead {
+	data: Readonly<Ref<SidecarInfoPayload | null>>;
+	error: Readonly<Ref<unknown>>;
+	pending: Readonly<Ref<boolean>>;
+	/** The first read. */
+	execute: () => Promise<void>;
+	/** Reads the info again now. */
+	refresh: () => Promise<void>;
+}
+
+/**
+ * Opens the info read, polled every `interval` ms while it is above 0: the
+ * controller raises it while the sidecar comes back, and sets it to 0 once
+ * the sidecar answers or gives up.
+ */
+export type OpenSidecarInfoRead = (
+	interval: Readonly<Ref<number>>,
+) => SidecarInfoRead;
+
+/** The info of the read's last answer, or null when it failed. */
+function readInfo(read: SidecarInfoRead): SidecarInfo | null {
+	const body = read.data.value;
+	if (read.error.value || !body) return null;
+	return {
+		isRunning: body.isRunning === true,
+		hasGivenUp: body.hasGivenUp === true,
+		disabled: body.disabled === true,
+	};
 }
 
 export function createSidecarStatusController(
-	fetchDetails: FetchSidecarInfo,
+	openRead: OpenSidecarInfoRead,
 ): SidecarStatusController {
 	const backoff = createBackoff();
 	const subscribers = new Set<(status: SidecarStatus) => void>();
+	const pollInterval = ref(0);
 	let status: SidecarStatus = SIDECAR_STATUS_CONNECTING;
-	let pollTimer: ReturnType<typeof setTimeout> | null = null;
 	let disposed = false;
+	const read = openRead(readonly(pollInterval));
 
 	function notify(): void {
 		for (const cb of subscribers) cb(status);
@@ -74,18 +96,8 @@ export function createSidecarStatusController(
 		notify();
 	}
 
-	function schedulePoll(): void {
-		if (disposed || pollTimer !== null) return;
-		const delay = nextDelay(backoff, SIDECAR_POLL_DELAYS_MS);
-		pollTimer = setTimeout(() => {
-			pollTimer = null;
-			void poll();
-		}, delay);
-	}
-
-	async function poll(): Promise<void> {
-		if (disposed) return;
-		handleInfo(await fetchInfo(fetchDetails));
+	function keepPolling(): void {
+		pollInterval.value = nextDelay(backoff, SIDECAR_POLL_DELAYS_MS);
 	}
 
 	function handleInfo(info: SidecarInfo | null): void {
@@ -93,31 +105,56 @@ export function createSidecarStatusController(
 		// Probe itself failed (backend momentarily unreachable): keep waiting.
 		if (info === null) {
 			setStatus(SIDECAR_STATUS_REVIVING);
-			schedulePoll();
+			keepPolling();
 			return;
 		}
 		if (info.hasGivenUp) {
+			pollInterval.value = 0;
 			setStatus(SIDECAR_STATUS_UNAVAILABLE);
 			return;
 		}
 		if (info.isRunning) {
 			resetBackoff(backoff);
+			pollInterval.value = 0;
 			setStatus(SIDECAR_STATUS_CONNECTED);
 			return;
 		}
 		// Down but not terminal — the probe already asked the backend to respawn;
 		// keep polling until it reports the sidecar running.
 		setStatus(SIDECAR_STATUS_REVIVING);
-		schedulePoll();
+		keepPolling();
+	}
+
+	// Each answer, a probe's or the polling's, moves the status.
+	const stopFollowing = watch(
+		read.pending,
+		(isPending, wasPending) => {
+			if (wasPending && !isPending) handleInfo(readInfo(read));
+		},
+		{ flush: "sync" },
+	);
+
+	function dispose(): void {
+		disposed = true;
+		pollInterval.value = 0;
+		stopFollowing();
+		subscribers.clear();
+	}
+
+	function probeAgain(): void {
+		if (disposed) return;
+		resetBackoff(backoff);
+		setStatus(SIDECAR_STATUS_REVIVING);
+		void read.refresh();
 	}
 
 	return {
 		init: async (): Promise<boolean> => {
-			const info = await fetchInfo(fetchDetails);
-			if (info === null) return false;
-			if (info.disabled) return false;
-			handleInfo(info);
-			return true;
+			await read.execute();
+			const info = readInfo(read);
+			if (info !== null && !info.disabled) return true;
+			dispose();
+			return false;
 		},
 		getStatus: () => status,
 		subscribe: (cb) => {
@@ -128,29 +165,14 @@ export function createSidecarStatusController(
 			};
 		},
 		reportChannelDown: () => {
-			if (disposed) return;
 			if (status !== SIDECAR_STATUS_CONNECTED) return;
 			// Surface the drop right away (amber dot + spinner) instead of waiting on
 			// the re-probe: that probe awaits a respawn and can take a second or two,
-			// during which the icon would otherwise look healthy. poll() flips back
-			// to connected once the sidecar answers again.
-			resetBackoff(backoff);
-			setStatus(SIDECAR_STATUS_REVIVING);
-			void poll();
-		},
-		retry: () => {
-			if (disposed) return;
-			resetBackoff(backoff);
-			setStatus(SIDECAR_STATUS_REVIVING);
-			void poll();
-		},
-		dispose: () => {
-			disposed = true;
-			if (pollTimer !== null) {
-				clearTimeout(pollTimer);
-				pollTimer = null;
-			}
-			subscribers.clear();
+			// during which the icon would otherwise look healthy. The answer flips
+			// back to connected once the sidecar answers again.
+			probeAgain();
 		},
+		retry: probeAgain,
+		dispose,
 	};
 }