Skip to content

πŸ™Œ OpenHands: AI-Driven Development

feat: execute git-info probe commands over bash-events WebSocket (#646)

Tim O'Farrell2d494a476763
diff --git a/src/hooks/query/use-local-git-info.ts b/src/hooks/query/use-local-git-info.ts
index d962eff029..f7657c644f 100644
--- a/src/hooks/query/use-local-git-info.ts
+++ b/src/hooks/query/use-local-git-info.ts
@@ -1,11 +1,11 @@
import { useQuery } from "@tanstack/react-query";
+import { useRef } from "react";
-import AgentServerRuntimeService, {
- CommandResult,
-} from "#/api/runtime-service/agent-server-runtime-service";
+import type { CommandResult } from "#/api/runtime-service/agent-server-runtime-service";
import { getAgentServerWorkingDir } from "#/api/agent-server-config";
import { useActiveConversation } from "#/hooks/query/use-active-conversation";
import { useRuntimeIsReady } from "#/hooks/use-runtime-is-ready";
+import { useBashCommandRunner } from "#/hooks/use-bash-command-runner";
import { Provider } from "#/types/settings";
import { parseGitRemoteUrl } from "#/utils/parse-git-remote-url";
@@ -83,14 +83,19 @@ async function probeNestedRepoInDir(
}
/**
- * Probe git metadata directly from the workspace checkout via the agent server
- * (`git remote get-url origin`, `git rev-parse --abbrev-ref HEAD`).
+ * Probe git metadata directly from the workspace checkout via the agent
+ * server's bash-events WebSocket (`git remote get-url origin`,
+ * `git rev-parse --abbrev-ref HEAD`).
*
* We intentionally keep this probe enabled until the active conversation has
* a complete repo tuple (`selected_repository`, `git_provider`,
* `selected_branch`) so the control bar can recover from partial metadata
* hydration after connect/clone flows.
*
+ * Commands are executed over a persistent WebSocket connection
+ * (`/sockets/bash-events`) rather than individual REST calls, which avoids
+ * the per-request HTTP overhead of the previous polling approach.
+ *
* Returns `null` fields when the working dir is not a git checkout β€” callers
* should treat that the same as "no repo detected".
*/
@@ -107,6 +112,31 @@ export const useLocalGitInfo = () => {
const hasConversationProvider = !!conversation?.git_provider;
const hasConversationBranch = !!conversation?.selected_branch;
+ const queryEnabled =
+ runtimeIsReady &&
+ !!conversationId &&
+ (!hasConversationRepo ||
+ !hasConversationProvider ||
+ !hasConversationBranch);
+
+ // Persistent WebSocket connection to the bash-events endpoint. The
+ // connection is opened when the query is enabled and closed on unmount or
+ // when the conversation changes.
+ const runCommand = useBashCommandRunner(
+ conversationUrl,
+ sessionApiKey,
+ queryEnabled,
+ );
+
+ // Keep a ref so queryFn can call the latest runner without capturing it
+ // as a queryKey dependency (runCommand is stable but the linter can't
+ // infer that).
+ const runCommandRef = useRef(runCommand);
+ runCommandRef.current = runCommand;
+
+ // runCommandRef is a ref (always stable); the linter cannot infer this so
+ // we disable the exhaustive-deps check here.
+ // eslint-disable-next-line @tanstack/query/exhaustive-deps
return useQuery<LocalGitInfo>({
queryKey: [
"local-git-info",
@@ -117,13 +147,7 @@ export const useLocalGitInfo = () => {
],
queryFn: async () => {
const run: RunCommand = (command, cwd, timeout) =>
- AgentServerRuntimeService.executeCommand(
- conversationUrl,
- sessionApiKey,
- command,
- cwd,
- timeout,
- );
+ runCommandRef.current(command, cwd, timeout);
const directInfo = await probeGitInfoAtDir(run, workingDir);
if (directInfo.repository || directInfo.branch) return directInfo;
@@ -134,17 +158,13 @@ export const useLocalGitInfo = () => {
return EMPTY_LOCAL_GIT_INFO;
},
- enabled:
- runtimeIsReady &&
- !!conversationId &&
- (!hasConversationRepo ||
- !hasConversationProvider ||
- !hasConversationBranch),
+ enabled: queryEnabled,
retry: false,
// Re-probe the workspace every 10s so the UI reflects branch/repo
// changes (e.g. `git checkout`, adding a remote) without requiring a
// manual refresh when there is no `selected_repository` recorded on
- // the conversation.
+ // the conversation. Commands now run over the persistent WebSocket
+ // connection rather than individual REST calls.
staleTime: 10_000,
refetchInterval: 10_000,
gcTime: 1000 * 60 * 5,
diff --git a/src/hooks/use-bash-command-runner.ts b/src/hooks/use-bash-command-runner.ts
new file mode 100644
index 0000000000..dd57dbd8d9
--- /dev/null
+++ b/src/hooks/use-bash-command-runner.ts
@@ -0,0 +1,191 @@
+import { useCallback, useEffect, useRef } from "react";
+import type {
+ BashCommand,
+ BashError,
+ BashEvent,
+ BashOutput,
+} from "@openhands/typescript-client";
+import type { CommandResult } from "#/api/runtime-service/agent-server-runtime-service";
+import { buildBashWebSocketUrl } from "#/utils/websocket-url";
+
+interface WaitingCommand {
+ command: string;
+ cwd: string;
+ timeout: number;
+ resolve: (result: CommandResult) => void;
+ reject: (error: Error) => void;
+}
+
+interface PendingCommand {
+ resolve: (result: CommandResult) => void;
+ reject: (error: Error) => void;
+}
+
+interface ActiveCommand extends PendingCommand {
+ stdout: string[];
+ stderr: string[];
+}
+
+export type BashCommandRunner = (
+ command: string,
+ cwd: string,
+ timeout: number,
+) => Promise<CommandResult>;
+
+function isBashCommand(event: BashEvent): event is BashCommand {
+ return event.kind === "BashCommand";
+}
+
+function isBashOutput(event: BashEvent): event is BashOutput {
+ return event.kind === "BashOutput";
+}
+
+function isBashError(event: BashEvent): event is BashError {
+ return event.kind === "BashError";
+}
+
+/**
+ * Maintains a persistent WebSocket connection to the agent-server's
+ * `/sockets/bash-events` endpoint and exposes a `runCommand` function that
+ * executes a bash command and returns a Promise that resolves when the
+ * final `BashOutput` (non-null `exit_code`) arrives.
+ *
+ * Commands are correlated using a FIFO queue: each `BashCommand` echo
+ * received from the server is paired with the oldest outstanding request in
+ * the queue, and subsequent `BashOutput` events are matched by `command_id`.
+ *
+ * Commands queued while the socket is still in the CONNECTING state are
+ * buffered and flushed automatically when the socket opens.
+ */
+export function useBashCommandRunner(
+ conversationUrl: string | null | undefined,
+ sessionApiKey: string | null | undefined,
+ enabled: boolean,
+): BashCommandRunner {
+ const wsRef = useRef<WebSocket | null>(null);
+ // Commands waiting for the socket to transition from CONNECTING β†’ OPEN
+ const connectingQueueRef = useRef<WaitingCommand[]>([]);
+ // Commands whose request was sent; waiting for the BashCommand echo to get command_id
+ const pendingQueueRef = useRef<PendingCommand[]>([]);
+ // Commands whose command_id is known; waiting for BashOutput with non-null exit_code
+ const activeCommandsRef = useRef<Map<string, ActiveCommand>>(new Map());
+
+ useEffect(() => {
+ if (!enabled) return;
+
+ const wsUrl = buildBashWebSocketUrl(conversationUrl, sessionApiKey);
+ const ws = new WebSocket(wsUrl);
+ wsRef.current = ws;
+
+ ws.onopen = () => {
+ // Flush any commands that arrived while connecting
+ for (const {
+ command,
+ cwd,
+ timeout,
+ resolve,
+ reject,
+ } of connectingQueueRef.current) {
+ pendingQueueRef.current.push({ resolve, reject });
+ ws.send(JSON.stringify({ command, cwd, timeout }));
+ }
+ connectingQueueRef.current = [];
+ };
+
+ ws.onmessage = (event: MessageEvent) => {
+ let data: BashEvent;
+ try {
+ data = JSON.parse(event.data as string) as BashEvent;
+ } catch {
+ return; // ignore malformed frames
+ }
+
+ if (isBashCommand(data)) {
+ // Associate the next pending request with the server-assigned command_id
+ const pending = pendingQueueRef.current.shift();
+ if (pending) {
+ activeCommandsRef.current.set(data.id, {
+ ...pending,
+ stdout: [],
+ stderr: [],
+ });
+ }
+ } else if (isBashOutput(data) && data.command_id) {
+ const active = activeCommandsRef.current.get(data.command_id);
+ if (active) {
+ if (data.stdout) active.stdout.push(data.stdout);
+ if (data.stderr) active.stderr.push(data.stderr);
+ if (data.exit_code != null) {
+ activeCommandsRef.current.delete(data.command_id);
+ active.resolve({
+ exit_code: data.exit_code,
+ stdout: active.stdout.join(""),
+ stderr: active.stderr.join(""),
+ });
+ }
+ }
+ } else if (isBashError(data)) {
+ rejectAll(`Bash error: ${data.code}: ${data.detail}`);
+ }
+ };
+
+ function rejectAll(reason: string): void {
+ const err = new Error(reason);
+ for (const { reject: rej } of connectingQueueRef.current) rej(err);
+ connectingQueueRef.current = [];
+ for (const p of pendingQueueRef.current) p.reject(err);
+ pendingQueueRef.current = [];
+ for (const a of activeCommandsRef.current.values()) a.reject(err);
+ activeCommandsRef.current.clear();
+ }
+
+ ws.onclose = () => {
+ wsRef.current = null;
+ rejectAll("Bash WebSocket closed");
+ };
+
+ ws.onerror = () => {
+ wsRef.current = null;
+ rejectAll("Bash WebSocket error");
+ };
+
+ return () => {
+ // Prevent the close/error handlers from double-rejecting after unmount
+ ws.onclose = null;
+ ws.onerror = null;
+ ws.close();
+ wsRef.current = null;
+ rejectAll("Bash WebSocket unmounted");
+ };
+ }, [enabled, conversationUrl, sessionApiKey]);
+
+ const runCommand: BashCommandRunner = useCallback(
+ (command: string, cwd: string, timeout: number) =>
+ new Promise<CommandResult>((resolve, reject) => {
+ const ws = wsRef.current;
+ if (
+ !ws ||
+ ws.readyState === WebSocket.CLOSED ||
+ ws.readyState === WebSocket.CLOSING
+ ) {
+ reject(new Error("Bash WebSocket not available"));
+ return;
+ }
+ if (ws.readyState === WebSocket.CONNECTING) {
+ connectingQueueRef.current.push({
+ command,
+ cwd,
+ timeout,
+ resolve,
+ reject,
+ });
+ } else {
+ pendingQueueRef.current.push({ resolve, reject });
+ ws.send(JSON.stringify({ command, cwd, timeout }));
+ }
+ }),
+ [],
+ );
+
+ return runCommand;
+}
diff --git a/src/utils/websocket-url.ts b/src/utils/websocket-url.ts
index 21cdf524f9..289ce09d90 100644
--- a/src/utils/websocket-url.ts
+++ b/src/utils/websocket-url.ts
@@ -75,6 +75,34 @@ function getConversationUrlProtocol(
}
}
+/**
+ * Builds the WebSocket URL for the agent-server's bash-events endpoint.
+ * The URL is derived from the same host and path prefix as the conversation
+ * events socket so it works in both direct-connect and reverse-proxy deployments.
+ *
+ * @param conversationUrl The conversation URL containing host/port
+ * @param sessionApiKey Optional session API key (appended as query param)
+ * @returns WebSocket URL for the bash-events endpoint
+ */
+export function buildBashWebSocketUrl(
+ conversationUrl: string | null | undefined,
+ sessionApiKey?: string | null,
+): string {
+ const baseHost = extractBaseHost(conversationUrl);
+ const pathPrefix = extractPathPrefix(conversationUrl);
+
+ const pageIsSecure = window.location.protocol === "https:";
+ const targetIsSecure =
+ getConversationUrlProtocol(conversationUrl) === "https:";
+ const protocol = pageIsSecure || targetIsSecure ? "wss:" : "ws:";
+
+ const base = `${protocol}//${baseHost}${pathPrefix}/sockets/bash-events`;
+ if (sessionApiKey) {
+ return `${base}?session_api_key=${encodeURIComponent(sessionApiKey)}`;
+ }
+ return base;
+}
+
/**
* Builds the WebSocket URL for V1 conversations (without query params)
* @param conversationId The conversation ID