🙌 OpenHands: AI-Driven Development
feat(frontend): add /btw side-channel command for asking the agent mid-task (#13918)
Vasco Schiavod548665bcf39
diff --git a/frontend/__tests__/components/chat/btw-messages.test.tsx b/frontend/__tests__/components/chat/btw-messages.test.tsxnew file mode 100644index 0000000000..38956aac8c--- /dev/null+++ b/frontend/__tests__/components/chat/btw-messages.test.tsx@@ -0,0 +1,39 @@+import { render, screen } from "@testing-library/react";+import userEvent from "@testing-library/user-event";+import { beforeEach, describe, expect, it } from "vitest";+import { BtwMessages } from "#/components/features/chat/btw-messages";+import { useBtwStore } from "#/stores/btw-store";++const CONV = "conv-1";+const entriesFor = (c: string) =>+ useBtwStore.getState().entriesByConversation[c] ?? [];++describe("<BtwMessages />", () => {+ beforeEach(() => {+ useBtwStore.setState({ entriesByConversation: {} });+ });++ it("renders spinner and no Got it button while pending", () => {+ useBtwStore.getState().addPending(CONV, "why?");+ render(<BtwMessages conversationId={CONV} />);+ expect(screen.getByText("why?")).toBeInTheDocument();+ expect(screen.getByTestId("btw-spinner")).toBeInTheDocument();+ expect(screen.queryByRole("button", { name: /got it/i })).toBeNull();+ });++ it("renders the response and a Got it button that dismisses on click", async () => {+ const id = useBtwStore.getState().addPending(CONV, "why?");+ useBtwStore.getState().resolve(CONV, id, "because");+ const user = userEvent.setup();+ render(<BtwMessages conversationId={CONV} />);+ expect(screen.getByText(/because/i)).toBeInTheDocument();+ await user.click(screen.getByRole("button", { name: /got it/i }));+ expect(entriesFor(CONV)).toEqual([]);+ });++ it("does not render entries from other conversations", () => {+ useBtwStore.getState().addPending("other-conv", "not mine");+ const { container } = render(<BtwMessages conversationId={CONV} />);+ expect(container).toBeEmptyDOMElement();+ });+});diff --git a/frontend/__tests__/hooks/chat/use-btw-interceptor.test.ts b/frontend/__tests__/hooks/chat/use-btw-interceptor.test.tsnew file mode 100644index 0000000000..b1a2397663--- /dev/null+++ b/frontend/__tests__/hooks/chat/use-btw-interceptor.test.ts@@ -0,0 +1,66 @@+import { act, renderHook, waitFor } from "@testing-library/react";+import { beforeEach, describe, expect, it, vi } from "vitest";+import { useBtwInterceptor } from "#/hooks/chat/use-btw-interceptor";+import { useBtwStore } from "#/stores/btw-store";++const mockAskV1Agent = vi.hoisted(() =>+ vi.fn<(id: string, q: string) => Promise<{ response: string }>>(),+);++vi.mock("#/hooks/mutation/conversation-mutation-utils", () => ({+ askV1Agent: (id: string, q: string) => mockAskV1Agent(id, q),+}));++const CONV = "conv-1";+const entries = () =>+ useBtwStore.getState().entriesByConversation[CONV] ?? [];++describe("useBtwInterceptor", () => {+ beforeEach(() => {+ useBtwStore.setState({ entriesByConversation: {} });+ mockAskV1Agent.mockReset();+ });++ it("falls through to onSubmit for non-/btw messages", () => {+ const onSubmit = vi.fn();+ const { result } = renderHook(() => useBtwInterceptor(CONV, onSubmit));+ act(() => result.current("hello world"));+ expect(onSubmit).toHaveBeenCalledWith("hello world");+ expect(mockAskV1Agent).not.toHaveBeenCalled();+ expect(entries()).toEqual([]);+ });++ it("intercepts /btw, calls askV1Agent, and resolves the entry", async () => {+ mockAskV1Agent.mockResolvedValueOnce({ response: "because" });+ const onSubmit = vi.fn();+ const { result } = renderHook(() => useBtwInterceptor(CONV, onSubmit));++ act(() => result.current("/btw why?"));++ expect(onSubmit).not.toHaveBeenCalled();+ expect(mockAskV1Agent).toHaveBeenCalledWith(CONV, "why?");+ expect(entries()[0]).toMatchObject({ question: "why?", status: "pending" });++ await waitFor(() => expect(entries()[0].status).toBe("done"));+ expect(entries()[0]).toMatchObject({+ response: "because",+ status: "done",+ });+ });++ it("marks the entry as error when askV1Agent rejects", async () => {+ mockAskV1Agent.mockRejectedValueOnce(new Error("boom"));+ const { result } = renderHook(() => useBtwInterceptor(CONV, vi.fn()));+ act(() => result.current("/btw why?"));+ await waitFor(() => expect(entries()[0].status).toBe("error"));+ expect(entries()[0].response).toBe("boom");+ });++ it("falls through when conversationId is null (feature off for V0)", () => {+ const onSubmit = vi.fn();+ const { result } = renderHook(() => useBtwInterceptor(null, onSubmit));+ act(() => result.current("/btw why?"));+ expect(onSubmit).toHaveBeenCalledWith("/btw why?");+ expect(mockAskV1Agent).not.toHaveBeenCalled();+ });+});diff --git a/frontend/__tests__/stores/btw-store.test.ts b/frontend/__tests__/stores/btw-store.test.tsnew file mode 100644index 0000000000..d96d7dead4--- /dev/null+++ b/frontend/__tests__/stores/btw-store.test.ts@@ -0,0 +1,44 @@+import { beforeEach, describe, expect, it } from "vitest";+import { useBtwStore } from "#/stores/btw-store";++const CONV_A = "conv-a";+const CONV_B = "conv-b";++const entriesFor = (conv: string) =>+ useBtwStore.getState().entriesByConversation[conv] ?? [];++describe("btw store", () => {+ beforeEach(() => {+ useBtwStore.setState({ entriesByConversation: {} });+ });++ it("adds a pending entry scoped to the given conversation", () => {+ const id = useBtwStore.getState().addPending(CONV_A, "why?");+ expect(entriesFor(CONV_A)).toEqual([+ { id, question: "why?", status: "pending" },+ ]);+ expect(entriesFor(CONV_B)).toEqual([]);+ });++ it("resolve and fail update status and response", () => {+ const id = useBtwStore.getState().addPending(CONV_A, "why?");+ useBtwStore.getState().resolve(CONV_A, id, "because");+ expect(entriesFor(CONV_A)[0]).toMatchObject({+ status: "done",+ response: "because",+ });+ useBtwStore.getState().fail(CONV_A, id, "boom");+ expect(entriesFor(CONV_A)[0]).toMatchObject({+ status: "error",+ response: "boom",+ });+ });++ it("dismiss removes only the targeted entry in the scoped conversation", () => {+ const aId = useBtwStore.getState().addPending(CONV_A, "qa");+ useBtwStore.getState().addPending(CONV_B, "qb");+ useBtwStore.getState().dismiss(CONV_A, aId);+ expect(entriesFor(CONV_A)).toEqual([]);+ expect(entriesFor(CONV_B)).toHaveLength(1);+ });+});diff --git a/frontend/src/api/conversation-service/v1-conversation-service.api.ts b/frontend/src/api/conversation-service/v1-conversation-service.api.tsindex 1b0c9a0b95..47f60a4b96 100644--- a/frontend/src/api/conversation-service/v1-conversation-service.api.ts+++ b/frontend/src/api/conversation-service/v1-conversation-service.api.ts@@ -206,6 +206,34 @@ class V1ConversationService {return data;}+ /**+ * Ask the agent a side question without queueing a full turn.+ * @param conversationId The conversation ID+ * @param conversationUrl The conversation URL+ * @param question The side question to ask+ * @param sessionApiKey Session API key for authentication+ * @returns The agent's response+ */+ static async askAgent(+ conversationId: string,+ conversationUrl: string | null | undefined,+ question: string,+ sessionApiKey?: string | null,+ ): Promise<{ response: string }> {+ const url = this.buildRuntimeUrl(+ conversationUrl,+ `/api/conversations/${conversationId}/ask_agent`,+ );+ const headers = buildSessionHeaders(sessionApiKey);++ const { data } = await axios.post<{ response: string }>(+ url,+ { question },+ { headers },+ );+ return data;+ }+/*** Resume a V1 conversation* Uses the custom runtime URL from the conversationdiff --git a/frontend/src/components/features/chat/btw-messages.tsx b/frontend/src/components/features/chat/btw-messages.tsxnew file mode 100644index 0000000000..28528467fb--- /dev/null+++ b/frontend/src/components/features/chat/btw-messages.tsx@@ -0,0 +1,69 @@+import CheckCircle from "#/icons/check-circle-solid.svg?react";+import { useBtwStore } from "#/stores/btw-store";+import { GenericEventMessage } from "./generic-event-message";++function GotItButton({ onClick }: { onClick: () => void }) {+ return (+ <button+ type="button"+ onClick={onClick}+ className="flex items-center gap-1.5 px-3 py-1 rounded-full text-xs font-medium text-success bg-success/10 hover:bg-success/20 border border-success/30 transition-colors"+ >+ <CheckCircle className="w-3.5 h-3.5 fill-success" />+ {/* eslint-disable-next-line i18next/no-literal-string */}+ <span>Got it</span>+ </button>+ );+}++export interface BtwMessagesProps {+ conversationId: string | null | undefined;+}++export function BtwMessages({ conversationId }: BtwMessagesProps) {+ const entriesById = useBtwStore((s) => s.entriesByConversation);+ const dismiss = useBtwStore((s) => s.dismiss);+ const entries = conversationId ? (entriesById[conversationId] ?? []) : [];++ if (!conversationId || entries.length === 0) return null;++ return (+ <div data-testid="btw-messages" className="flex flex-col w-full">+ {entries.map((entry) => {+ const isPending = entry.status === "pending";+ return (+ <GenericEventMessage+ key={entry.id}+ title={+ <span className="flex items-center gap-2">+ {/* eslint-disable-next-line i18next/no-literal-string */}+ <span className="opacity-60">BTW:</span>+ <span>{entry.question}</span>+ {isPending && (+ <span+ data-testid="btw-spinner"+ className="inline-block w-3.5 h-3.5 ml-2 rounded-full border-2 border-neutral-500 border-t-transparent animate-spin"+ />+ )}+ </span>+ }+ details={+ isPending+ ? "Waiting for the agent's answer…"+ : (entry.response ?? "")+ }+ initiallyExpanded={!isPending}+ chevronPosition="before"+ titleTrailing={+ !isPending && (+ <GotItButton+ onClick={() => dismiss(conversationId, entry.id)}+ />+ )+ }+ />+ );+ })}+ </div>+ );+}diff --git a/frontend/src/components/features/chat/chat-interface.tsx b/frontend/src/components/features/chat/chat-interface.tsxindex 51eaaff120..f7cb0bcb8c 100644--- a/frontend/src/components/features/chat/chat-interface.tsx+++ b/frontend/src/components/features/chat/chat-interface.tsx@@ -4,6 +4,7 @@ import { useParams } from "react-router";import { useTranslation } from "react-i18next";import { convertImageToBase64 } from "#/utils/convert-image-to-base-64";import { createChatMessage } from "#/services/chat-service";+import { BtwMessages } from "./btw-messages";import { InteractiveChatBox } from "./interactive-chat-box";import { AgentState } from "#/types/agent-state";import { useFilteredEvents } from "#/hooks/use-filtered-events";@@ -291,6 +292,7 @@ export function ChatInterface() {</div><div className="flex flex-col gap-[6px]">+ <BtwMessages conversationId={params.conversationId} /><div className="flex justify-between relative"><div className="flex items-end gap-1"><ConfirmationModeEnabled />diff --git a/frontend/src/components/features/chat/generic-event-message.tsx b/frontend/src/components/features/chat/generic-event-message.tsxindex ff2ab633b1..e82d11e927 100644--- a/frontend/src/components/features/chat/generic-event-message.tsx+++ b/frontend/src/components/features/chat/generic-event-message.tsx@@ -10,6 +10,10 @@ interface GenericEventMessageProps {details: string | React.ReactNode;success?: ObservationResultStatus;initiallyExpanded?: boolean;+ /** Where to place the expand/collapse chevron relative to the title. */+ chevronPosition?: "before" | "after";+ /** Extra content rendered at the end of the title row (right side). */+ titleTrailing?: React.ReactNode;}export function GenericEventMessage({@@ -17,30 +21,47 @@ export function GenericEventMessage({details,success,initiallyExpanded = false,+ chevronPosition = "after",+ titleTrailing,}: GenericEventMessageProps) {const [showDetails, setShowDetails] = React.useState(initiallyExpanded);+ const chevron = details ? (+ <button+ type="button"+ onClick={() => setShowDetails((prev) => !prev)}+ className="cursor-pointer text-left"+ aria-label={showDetails ? "Collapse" : "Expand"}+ >+ {showDetails ? (+ <ArrowUp+ className={`h-4 w-4 inline fill-neutral-300 ${+ chevronPosition === "after" ? "ml-2" : "mr-2"+ }`}+ />+ ) : (+ <ArrowDown+ className={`h-4 w-4 inline fill-neutral-300 ${+ chevronPosition === "after" ? "ml-2" : "mr-2"+ }`}+ />+ )}+ </button>+ ) : null;+return (<div className="flex flex-col gap-2 border-l-2 pl-2 my-2 py-2 border-neutral-300 text-sm w-full"><div className="flex items-center justify-between font-bold text-neutral-300">- <div>+ <div className="flex items-center">+ {chevronPosition === "before" && chevron}{title}- {details && (- <button- type="button"- onClick={() => setShowDetails((prev) => !prev)}- className="cursor-pointer text-left"- >- {showDetails ? (- <ArrowUp className="h-4 w-4 ml-2 inline fill-neutral-300" />- ) : (- <ArrowDown className="h-4 w-4 ml-2 inline fill-neutral-300" />- )}- </button>- )}+ {chevronPosition === "after" && chevron}</div>- {success && <SuccessIndicator status={success} />}+ <div className="flex items-center">+ {titleTrailing}+ {success && <SuccessIndicator status={success} />}+ </div></div>{showDetails &&diff --git a/frontend/src/components/features/chat/interactive-chat-box.tsx b/frontend/src/components/features/chat/interactive-chat-box.tsxindex 92819286fc..eaa8532776 100644--- a/frontend/src/components/features/chat/interactive-chat-box.tsx+++ b/frontend/src/components/features/chat/interactive-chat-box.tsx@@ -2,6 +2,7 @@ import { isFileImage } from "#/utils/is-file-image";import { displayErrorToast } from "#/utils/custom-toast-handlers";import { validateFiles } from "#/utils/file-validation";import { CustomChatInput } from "./custom-chat-input";+import { useBtwInterceptor } from "#/hooks/chat/use-btw-interceptor";import { AgentState } from "#/types/agent-state";import { useActiveConversation } from "#/hooks/query/use-active-conversation";import { GitControlBar } from "./git-control-bar";@@ -137,10 +138,13 @@ export function InteractiveChatBox({}};- const handleSubmit = (message: string) => {- onSubmit(message, images, files);- clearAllFiles();- };+ const handleSubmit = useBtwInterceptor(+ conversation?.id ?? null,+ (message) => {+ onSubmit(message, images, files);+ clearAllFiles();+ },+ );const handleSuggestionsClick = (suggestion: string) => {handleSubmit(suggestion);diff --git a/frontend/src/hooks/chat/use-btw-interceptor.ts b/frontend/src/hooks/chat/use-btw-interceptor.tsnew file mode 100644index 0000000000..ee139f3fb2--- /dev/null+++ b/frontend/src/hooks/chat/use-btw-interceptor.ts@@ -0,0 +1,41 @@+import { useCallback } from "react";+import { askV1Agent } from "#/hooks/mutation/conversation-mutation-utils";+import { useBtwStore } from "#/stores/btw-store";+import { BTW_COMMAND } from "#/utils/constants";++const BTW_PREFIX = `${BTW_COMMAND} `;++/**+ * Intercepts "/btw <question>" submissions and routes them through the+ * ask_agent side-channel. Everything else falls through to `onSubmit`.+ * Passthrough when `conversationId` is null (e.g. V0 conversations).+ */+export const useBtwInterceptor = (+ conversationId: string | null | undefined,+ onSubmit: (message: string) => void,+) => {+ const addPending = useBtwStore((s) => s.addPending);+ const resolve = useBtwStore((s) => s.resolve);+ const fail = useBtwStore((s) => s.fail);++ return useCallback(+ (message: string) => {+ const trimmed = message.trim();+ const isBtw = trimmed === BTW_COMMAND || trimmed.startsWith(BTW_PREFIX);+ if (!conversationId || !isBtw) {+ onSubmit(message);+ return;+ }+ const question = trimmed.slice(BTW_COMMAND.length).trim();+ if (!question) return;++ const entryId = addPending(conversationId, question);+ askV1Agent(conversationId, question)+ .then(({ response }) => resolve(conversationId, entryId, response))+ .catch((err) =>+ fail(conversationId, entryId, err?.message ?? "Failed to ask agent"),+ );+ },+ [conversationId, onSubmit, addPending, resolve, fail],+ );+};diff --git a/frontend/src/hooks/mutation/conversation-mutation-utils.ts b/frontend/src/hooks/mutation/conversation-mutation-utils.tsindex e6254d09b8..9e176a3712 100644--- a/frontend/src/hooks/mutation/conversation-mutation-utils.ts+++ b/frontend/src/hooks/mutation/conversation-mutation-utils.ts@@ -64,6 +64,23 @@ export const pauseV1Conversation = async (conversationId: string) => {);};+/**+ * Ask the agent a side question on a V1 conversation+ */+export const askV1Agent = async (+ conversationId: string,+ question: string,+): Promise<{ response: string }> => {+ const { conversationUrl, sessionApiKey } =+ await fetchV1ConversationData(conversationId);+ return V1ConversationService.askAgent(+ conversationId,+ conversationUrl,+ question,+ sessionApiKey,+ );+};+/*** Stops a V0 conversation using the legacy API*/diff --git a/frontend/src/stores/btw-store.ts b/frontend/src/stores/btw-store.tsnew file mode 100644index 0000000000..d56b030229--- /dev/null+++ b/frontend/src/stores/btw-store.ts@@ -0,0 +1,80 @@+import { create } from "zustand";+import { devtools } from "zustand/middleware";++export type BtwStatus = "pending" | "done" | "error";++export interface BtwEntry {+ id: string;+ question: string;+ response?: string;+ status: BtwStatus;+}++interface BtwState {+ entriesByConversation: Record<string, BtwEntry[]>;+}++interface BtwActions {+ addPending: (conversationId: string, question: string) => string;+ resolve: (conversationId: string, id: string, response: string) => void;+ fail: (conversationId: string, id: string, error: string) => void;+ dismiss: (conversationId: string, id: string) => void;+}++type BtwStore = BtwState & BtwActions;++const initialState: BtwState = { entriesByConversation: {} };++const updateEntries = (+ state: BtwState,+ conversationId: string,+ updater: (entries: BtwEntry[]) => BtwEntry[],+): Pick<BtwState, "entriesByConversation"> => ({+ entriesByConversation: {+ ...state.entriesByConversation,+ [conversationId]: updater(+ state.entriesByConversation[conversationId] ?? [],+ ),+ },+});++export const useBtwStore = create<BtwStore>()(+ devtools(+ (set) => ({+ ...initialState,+ addPending: (conversationId, question) => {+ const id = crypto.randomUUID();+ set((s) =>+ updateEntries(s, conversationId, (entries) => [+ ...entries,+ { id, question, status: "pending" },+ ]),+ );+ return id;+ },+ resolve: (conversationId, id, response) =>+ set((s) =>+ updateEntries(s, conversationId, (entries) =>+ entries.map((e) =>+ e.id === id ? { ...e, response, status: "done" } : e,+ ),+ ),+ ),+ fail: (conversationId, id, error) =>+ set((s) =>+ updateEntries(s, conversationId, (entries) =>+ entries.map((e) =>+ e.id === id ? { ...e, response: error, status: "error" } : e,+ ),+ ),+ ),+ dismiss: (conversationId, id) =>+ set((s) =>+ updateEntries(s, conversationId, (entries) =>+ entries.filter((e) => e.id !== id),+ ),+ ),+ }),+ { name: "BtwStore" },+ ),+);diff --git a/frontend/src/utils/constants.ts b/frontend/src/utils/constants.tsindex 6c2a2535bf..5593f6bb0a 100644--- a/frontend/src/utils/constants.ts+++ b/frontend/src/utils/constants.ts@@ -73,6 +73,9 @@ export const CHAT_INPUT = {// UI tolerance constantsexport const EPS = 1.5; // px tolerance for "near min" height comparisons+/** The /btw slash command — asks a side question via the ask_agent endpoint. */+export const BTW_COMMAND = "/btw";+/** Built-in slash commands surfaced in the menu for V1 conversations. */export const BUILT_IN_COMMANDS: SlashCommandItem[] = [{@@ -84,6 +87,15 @@ export const BUILT_IN_COMMANDS: SlashCommandItem[] = [},command: "/new",},+ {+ skill: {+ name: "btw",+ type: "agentskills",+ content: "Ask the agent a side question without derailing the main task",+ triggers: [BTW_COMMAND],+ },+ command: BTW_COMMAND,+ },];// Skill content metadata prefixes