Skip to content

🙌 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.tsx
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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 conversation
diff --git a/frontend/src/components/features/chat/btw-messages.tsx b/frontend/src/components/features/chat/btw-messages.tsx
new file mode 100644
index 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.tsx
index 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.tsx
index 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.tsx
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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 constants
export 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