chat-messages: add hitl module with types, hooks, bundle, approval cards, and edit panel.

surfsense_web/features/chat-messages/hitl/bundle/bundle-context.tsx

@@ -0,0 +1,157 @@
+"use client";
+
+import { createContext, type ReactNode, useCallback, useContext, useMemo, useState } from "react";
+import type { HitlDecision } from "../types";
+
+export type BundleSubmit = (orderedDecisions: HitlDecision[]) => void;
+
+export interface HitlBundleAPI {
+	toolCallIds: readonly string[];
+	currentStep: number;
+	stagedCount: number;
+	isInBundle: (toolCallId: string) => boolean;
+	isCurrentStep: (toolCallId: string) => boolean;
+	getStaged: (toolCallId: string) => HitlDecision | undefined;
+	stage: (toolCallId: string, decision: HitlDecision) => void;
+	goToStep: (i: number) => void;
+	next: () => void;
+	prev: () => void;
+	submit: () => void;
+}
+
+const HitlBundleContext = createContext<HitlBundleAPI | null>(null);
+const ToolCallIdContext = createContext<string | null>(null);
+
+export function useHitlBundle(): HitlBundleAPI | null {
+	return useContext(HitlBundleContext);
+}
+
+export function useToolCallIdContext(): string | null {
+	return useContext(ToolCallIdContext);
+}
+
+export function ToolCallIdProvider({
+	toolCallId,
+	children,
+}: {
+	toolCallId: string;
+	children: ReactNode;
+}) {
+	return <ToolCallIdContext.Provider value={toolCallId}>{children}</ToolCallIdContext.Provider>;
+}
+
+interface HitlBundleProviderProps {
+	toolCallIds: readonly string[] | null;
+	onSubmit: BundleSubmit;
+	children: ReactNode;
+}
+
+/**
+ * Coordinates N pending HITL decisions into ONE ordered submission.
+ *
+ * Active only when ``toolCallIds`` has 2+ entries (parallel interrupts);
+ * single-card interrupts bypass the bundle entirely (``useHitlDecision``
+ * fires the ``hitl-decision`` window event directly).
+ *
+ * Pager UX: ``tool-call-item.tsx`` reads ``isInBundle`` + ``isCurrentStep``
+ * to render only the current-step card; ``timeline.tsx`` mounts
+ * ``<PagerChrome />`` once when this Provider is active. Submission is
+ * user-initiated via the pager's "Submit decisions" button (calls
+ * ``submit()``); not auto.
+ */
+export function HitlBundleProvider({ toolCallIds, onSubmit, children }: HitlBundleProviderProps) {
+	const active = toolCallIds !== null && toolCallIds.length >= 2;
+	const ids = useMemo(() => (active ? [...toolCallIds] : []), [active, toolCallIds]);
+	const bundleKey = ids.join("|");
+
+	const [prevBundleKey, setPrevBundleKey] = useState(bundleKey);
+	const [staged, setStaged] = useState<Map<string, HitlDecision>>(() => new Map());
+	const [currentStep, setCurrentStep] = useState(0);
+	if (bundleKey !== prevBundleKey) {
+		setPrevBundleKey(bundleKey);
+		setStaged(new Map());
+		setCurrentStep(0);
+	}
+
+	const isInBundle = useCallback((tcId: string) => ids.includes(tcId), [ids]);
+	const isCurrentStep = useCallback(
+		(tcId: string) => active === true && ids[currentStep] === tcId,
+		[active, ids, currentStep]
+	);
+	const getStaged = useCallback((tcId: string) => staged.get(tcId), [staged]);
+	const stage = useCallback(
+		(tcId: string, decision: HitlDecision) => {
+			if (!active || !ids.includes(tcId)) return;
+			setStaged((prev) => {
+				const next = new Map(prev);
+				next.set(tcId, decision);
+				return next;
+			});
+			window.dispatchEvent(
+				new CustomEvent("hitl-stage", { detail: { toolCallId: tcId, decision } })
+			);
+			const idx = ids.indexOf(tcId);
+			if (idx >= 0 && idx < ids.length - 1) {
+				setCurrentStep(idx + 1);
+			}
+		},
+		[active, ids]
+	);
+	const goToStep = useCallback(
+		(i: number) => {
+			if (i < 0 || i >= ids.length) return;
+			setCurrentStep(i);
+		},
+		[ids.length]
+	);
+	const next = useCallback(() => {
+		setCurrentStep((s) => Math.min(s + 1, Math.max(0, ids.length - 1)));
+	}, [ids.length]);
+	const prev = useCallback(() => {
+		setCurrentStep((s) => Math.max(s - 1, 0));
+	}, []);
+
+	const submit = useCallback(() => {
+		if (!active) return;
+		if (staged.size !== ids.length) return;
+		const ordered: HitlDecision[] = [];
+		for (const tcId of ids) {
+			const d = staged.get(tcId);
+			if (!d) return;
+			ordered.push(d);
+		}
+		onSubmit(ordered);
+	}, [active, ids, staged, onSubmit]);
+
+	const value = useMemo<HitlBundleAPI | null>(() => {
+		if (!active) return null;
+		return {
+			toolCallIds: ids,
+			currentStep,
+			stagedCount: staged.size,
+			isInBundle,
+			isCurrentStep,
+			getStaged,
+			stage,
+			goToStep,
+			next,
+			prev,
+			submit,
+		};
+	}, [
+		active,
+		ids,
+		currentStep,
+		staged,
+		isInBundle,
+		isCurrentStep,
+		getStaged,
+		stage,
+		goToStep,
+		next,
+		prev,
+		submit,
+	]);
+
+	return <HitlBundleContext.Provider value={value}>{children}</HitlBundleContext.Provider>;
+}

surfsense_web/features/chat-messages/hitl/bundle/index.ts

@@ -0,0 +1,8 @@
+export type { BundleSubmit, HitlBundleAPI } from "./bundle-context";
+export {
+	HitlBundleProvider,
+	ToolCallIdProvider,
+	useHitlBundle,
+	useToolCallIdContext,
+} from "./bundle-context";
+export { PagerChrome } from "./pager-chrome";

surfsense_web/features/chat-messages/hitl/bundle/pager-chrome.tsx

@@ -0,0 +1,65 @@
+"use client";
+
+import { ChevronLeftIcon, ChevronRightIcon } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { useHitlBundle } from "./bundle-context";
+
+/**
+ * Prev/next nav and Submit for the current step of an active HITL bundle.
+ * Submission is gated on every action_request having a staged decision.
+ *
+ * Mounted ONCE by ``timeline.tsx`` when the bundle is active. Does NOT
+ * wrap individual cards. Reads bundle state via ``useHitlBundle()``;
+ * renders nothing when no bundle is active.
+ */
+export function PagerChrome() {
+	const bundle = useHitlBundle();
+	if (!bundle) return null;
+
+	const total = bundle.toolCallIds.length;
+	const step = bundle.currentStep;
+	const allStaged = bundle.stagedCount === total;
+
+	return (
+		<div className="mt-3 flex items-center gap-2 rounded-md border border-border bg-muted/40 p-2 text-sm">
+			<Button
+				type="button"
+				size="sm"
+				variant="outline"
+				onClick={bundle.prev}
+				disabled={step === 0}
+				aria-label="Previous approval"
+			>
+				<ChevronLeftIcon className="h-4 w-4" />
+			</Button>
+			<span className="font-medium tabular-nums">
+				{step + 1} / {total}
+			</span>
+			<span className="text-muted-foreground">·</span>
+			<span className="text-muted-foreground">
+				{bundle.stagedCount} of {total} decided
+			</span>
+			<Button
+				type="button"
+				size="sm"
+				variant="outline"
+				onClick={bundle.next}
+				disabled={step >= total - 1}
+				aria-label="Next approval"
+			>
+				<ChevronRightIcon className="h-4 w-4" />
+			</Button>
+			<div className="ml-auto">
+				<Button
+					type="button"
+					size="sm"
+					onClick={bundle.submit}
+					disabled={!allStaged}
+					title={allStaged ? "Submit decisions" : "Decide every action first"}
+				>
+					Submit decisions
+				</Button>
+			</div>
+		</div>
+	);
+}