Skip to content

πŸ™Œ OpenHands: AI-Driven Development

feat(frontend): show plan content in the planning tab (#11807)

Hiep Led9731b68509e
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 5ca7daf09a..bd37fa8180 100644
--- a/frontend/src/api/conversation-service/v1-conversation-service.api.ts
+++ b/frontend/src/api/conversation-service/v1-conversation-service.api.ts
@@ -296,6 +296,25 @@ class V1ConversationService {
const { data } = await openHands.get<{ runtime_id: string }>(url);
return data;
}
+
+ /**
+ * Read a file from a specific conversation's sandbox workspace
+ * @param conversationId The conversation ID
+ * @param filePath Path to the file to read within the sandbox workspace (defaults to /workspace/project/PLAN.md)
+ * @returns The content of the file or an empty string if the file doesn't exist
+ */
+ static async readConversationFile(
+ conversationId: string,
+ filePath: string = "/workspace/project/PLAN.md",
+ ): Promise<string> {
+ const params = new URLSearchParams();
+ params.append("file_path", filePath);
+
+ const { data } = await openHands.get<string>(
+ `/api/v1/app-conversations/${conversationId}/file?${params.toString()}`,
+ );
+ return data;
+ }
}
export default V1ConversationService;
diff --git a/frontend/src/components/features/markdown/headings.tsx b/frontend/src/components/features/markdown/headings.tsx
index 2e12fc7db4..3098a4514a 100644
--- a/frontend/src/components/features/markdown/headings.tsx
+++ b/frontend/src/components/features/markdown/headings.tsx
@@ -8,7 +8,7 @@ export function h1({
React.HTMLAttributes<HTMLHeadingElement> &
ExtraProps) {
return (
- <h1 className="text-[32px] text-white font-bold leading-8 mb-4 mt-6 first:mt-0">
+ <h1 className="text-2xl text-white font-bold leading-8 mb-4 mt-6 first:mt-0">
{children}
</h1>
);
diff --git a/frontend/src/contexts/conversation-websocket-context.tsx b/frontend/src/contexts/conversation-websocket-context.tsx
index b0b0119f75..ae115c41a9 100644
--- a/frontend/src/contexts/conversation-websocket-context.tsx
+++ b/frontend/src/contexts/conversation-websocket-context.tsx
@@ -26,6 +26,7 @@ import {
isExecuteBashActionEvent,
isExecuteBashObservationEvent,
isConversationErrorEvent,
+ isPlanningFileEditorObservationEvent,
} from "#/types/v1/type-guards";
import { ConversationStateUpdateEventStats } from "#/types/v1/core/events/conversation-state-event";
import { handleActionEventCacheInvalidation } from "#/utils/cache-utils";
@@ -38,6 +39,7 @@ import EventService from "#/api/event-service/event-service.api";
import { useConversationStore } from "#/state/conversation-store";
import { isBudgetOrCreditError } from "#/utils/error-handler";
import { useTracking } from "#/hooks/use-tracking";
+import { useReadConversationFile } from "#/hooks/mutation/use-read-conversation-file";
import useMetricsStore from "#/stores/metrics-store";
// eslint-disable-next-line @typescript-eslint/naming-convention
@@ -102,12 +104,22 @@ export function ConversationWebSocketProvider({
number | null
>(null);
- const { conversationMode } = useConversationStore();
+ const { conversationMode, setPlanContent } = useConversationStore();
+
+ // Hook for reading conversation file
+ const { mutate: readConversationFile } = useReadConversationFile();
// Separate received event count tracking per connection
const receivedEventCountRefMain = useRef(0);
const receivedEventCountRefPlanning = useRef(0);
+ // Track the latest PlanningFileEditorObservation event during history replay
+ // We'll only call the API once after history loading completes
+ const latestPlanningFileEventRef = useRef<{
+ path: string;
+ conversationId: string;
+ } | null>(null);
+
// Helper function to update metrics from stats event
const updateMetricsFromStats = useCallback(
(event: ConversationStateUpdateEventStats) => {
@@ -235,11 +247,40 @@ export function ConversationWebSocketProvider({
receivedEventCountRefPlanning,
]);
+ // Call API once after history loading completes if we tracked any PlanningFileEditorObservation events
+ useEffect(() => {
+ if (!isLoadingHistoryPlanning && latestPlanningFileEventRef.current) {
+ const { path, conversationId: currentPlanningConversationId } =
+ latestPlanningFileEventRef.current;
+
+ readConversationFile(
+ {
+ conversationId: currentPlanningConversationId,
+ filePath: path,
+ },
+ {
+ onSuccess: (fileContent) => {
+ setPlanContent(fileContent);
+ },
+ onError: (error) => {
+ // eslint-disable-next-line no-console
+ console.warn("Failed to read conversation file:", error);
+ },
+ },
+ );
+
+ // Clear the ref after calling the API
+ latestPlanningFileEventRef.current = null;
+ }
+ }, [isLoadingHistoryPlanning, readConversationFile, setPlanContent]);
+
useEffect(() => {
hasConnectedRefMain.current = false;
setIsLoadingHistoryPlanning(!!subConversationIds?.length);
setExpectedEventCountPlanning(null);
receivedEventCountRefPlanning.current = 0;
+ // Reset the tracked event ref when sub-conversations change
+ latestPlanningFileEventRef.current = null;
}, [subConversationIds]);
// Merged loading history state - true if either connection is still loading
@@ -254,6 +295,8 @@ export function ConversationWebSocketProvider({
setIsLoadingHistoryMain(true);
setExpectedEventCountMain(null);
receivedEventCountRefMain.current = 0;
+ // Reset the tracked event ref when conversation changes
+ latestPlanningFileEventRef.current = null;
}, [conversationId]);
// Separate message handlers for each connection
@@ -438,6 +481,41 @@ export function ConversationWebSocketProvider({
.join("\n");
appendOutput(textContent);
}
+
+ // Handle PlanningFileEditorObservation events - read and update plan content
+ if (isPlanningFileEditorObservationEvent(event)) {
+ const planningAgentConversation = subConversations?.[0];
+ const planningConversationId = planningAgentConversation?.id;
+
+ if (planningConversationId && event.observation.path) {
+ // During history replay, track the latest event but don't call API
+ // After history loading completes, we'll call the API once with the latest event
+ if (isLoadingHistoryPlanning) {
+ latestPlanningFileEventRef.current = {
+ path: event.observation.path,
+ conversationId: planningConversationId,
+ };
+ } else {
+ // History loading is complete - this is a new real-time event
+ // Call the API immediately for real-time updates
+ readConversationFile(
+ {
+ conversationId: planningConversationId,
+ filePath: event.observation.path,
+ },
+ {
+ onSuccess: (fileContent) => {
+ setPlanContent(fileContent);
+ },
+ onError: (error) => {
+ // eslint-disable-next-line no-console
+ console.warn("Failed to read conversation file:", error);
+ },
+ },
+ );
+ }
+ }
+ }
}
} catch (error) {
// eslint-disable-next-line no-console
@@ -455,6 +533,8 @@ export function ConversationWebSocketProvider({
setExecutionStatus,
appendInput,
appendOutput,
+ readConversationFile,
+ setPlanContent,
updateMetricsFromStats,
],
);
diff --git a/frontend/src/hooks/mutation/use-read-conversation-file.ts b/frontend/src/hooks/mutation/use-read-conversation-file.ts
new file mode 100644
index 0000000000..5dd8c51eb9
--- /dev/null
+++ b/frontend/src/hooks/mutation/use-read-conversation-file.ts
@@ -0,0 +1,17 @@
+import { useMutation } from "@tanstack/react-query";
+import V1ConversationService from "#/api/conversation-service/v1-conversation-service.api";
+
+interface UseReadConversationFileVariables {
+ conversationId: string;
+ filePath?: string;
+}
+
+export const useReadConversationFile = () =>
+ useMutation({
+ mutationKey: ["read-conversation-file"],
+ mutationFn: async ({
+ conversationId,
+ filePath,
+ }: UseReadConversationFileVariables): Promise<string> =>
+ V1ConversationService.readConversationFile(conversationId, filePath),
+ });
diff --git a/frontend/src/routes/planner-tab.tsx b/frontend/src/routes/planner-tab.tsx
index a3002c6651..4fb46f9939 100644
--- a/frontend/src/routes/planner-tab.tsx
+++ b/frontend/src/routes/planner-tab.tsx
@@ -23,7 +23,7 @@ function PlannerTab() {
const { planContent, setConversationMode } = useConversationStore();
- if (planContent) {
+ if (planContent !== null && planContent !== undefined) {
return (
<div className="flex flex-col w-full h-full p-4 overflow-auto">
<Markdown
diff --git a/frontend/src/state/conversation-store.ts b/frontend/src/state/conversation-store.ts
index 77186ce69c..cfbacc1f9a 100644
--- a/frontend/src/state/conversation-store.ts
+++ b/frontend/src/state/conversation-store.ts
@@ -56,6 +56,7 @@ interface ConversationActions {
setHasRightPanelToggled: (hasRightPanelToggled: boolean) => void;
setConversationMode: (conversationMode: ConversationMode) => void;
setSubConversationTaskId: (taskId: string | null) => void;
+ setPlanContent: (planContent: string | null) => void;
}
type ConversationStore = ConversationState & ConversationActions;
@@ -81,91 +82,7 @@ export const useConversationStore = create<ConversationStore>()(
submittedMessage: null,
shouldHideSuggestions: false,
hasRightPanelToggled: true,
- planContent: `
-# Improve Developer Onboarding and Examples
-
-## Overview
-
-Based on the analysis of Browser-Use's current documentation and examples, this plan addresses gaps in developer onboarding by creating a progressive learning path, troubleshooting resources, and practical examples that address real-world scenarios (like the LM Studio/local LLM integration issues encountered).
-
-## Current State Analysis
-
-**Strengths:**
-
-- Good quickstart documentation in \`docs/quickstart.mdx\`
-- Extensive examples across multiple categories (60+ example files)
-- Well-structured docs with multiple LLM provider examples
-- Active community support via Discord
-
-**Gaps Identified:**
-
-- No progressive tutorial series that builds complexity gradually
-- Limited troubleshooting documentation for common issues
-- Sparse comments in example files explaining what's happening
-- Local LLM setup (Ollama/LM Studio) not prominently featured
-- No "first 10 minutes" success path
-- Missing visual/conceptual architecture guides for beginners
-- Error messages don't always point to solutions
-
-## Proposed Improvements
-
-### 1. Create Interactive Tutorial Series (\`examples/tutorials/\`)
-
-**New folder structure:**
-
-\`\`\`
-examples/tutorials/
-β”œβ”€β”€ README.md # Tutorial overview and prerequisites
-β”œβ”€β”€ 00_hello_world.py # Absolute minimal example
-β”œβ”€β”€ 01_your_first_search.py # Basic search with detailed comments
-β”œβ”€β”€ 02_understanding_actions.py # How actions work
-β”œβ”€β”€ 03_data_extraction_basics.py # Extract data step-by-step
-β”œβ”€β”€ 04_error_handling.py # Common errors and solutions
-β”œβ”€β”€ 05_custom_tools_intro.py # First custom tool
-β”œβ”€β”€ 06_local_llm_setup.py # Ollama/LM Studio complete guide
-└── 07_debugging_tips.py # Debugging strategies
-\`\`\`
-
-**Key Features:**
-
-- Each file 50–80 lines max
-- Extensive inline comments explaining every concept
-- Clear learning objectives at the top of each file
-- "What you'll learn" and "Prerequisites" sections
-- Common pitfalls highlighted
-- Expected output shown in comments
-
-### 2. Troubleshooting Guide (\`docs/troubleshooting.mdx\`)
-
-**Sections:**
-
-- Installation issues (Chromium, dependencies, virtual environments)
-- LLM provider connection errors (API keys, timeouts, rate limits)
-- Local LLM setup (Ollama vs LM Studio, model compatibility)
-- Browser automation issues (element not found, timeout errors)
-- Common error messages with solutions
-- Performance optimization tips
-- When to ask for help (Discord/GitHub)
-
-**Format:**
-
-**Error: "LLM call timed out after 60 seconds"**
-
-**What it means:**
-The model took too long to respond
-
-**Common causes:**
-
-1. Model is too slow for the task
-2. LM Studio/Ollama not responding properly
-3. Complex page overwhelming the model
-
-**Solutions:**
-
-- Use flash_mode for faster execution
-- Try a faster model (Gemini Flash, GPT-4 Turbo Mini)
-- Simplify the task
-- Check model server logs`,
+ planContent: null,
conversationMode: "code",
subConversationTaskId: null,
@@ -304,6 +221,7 @@ The model took too long to respond
shouldHideSuggestions: false,
conversationMode: "code",
subConversationTaskId: null,
+ planContent: null,
},
false,
"resetConversationState",
@@ -317,6 +235,9 @@ The model took too long to respond
setSubConversationTaskId: (subConversationTaskId) =>
set({ subConversationTaskId }, false, "setSubConversationTaskId"),
+
+ setPlanContent: (planContent) =>
+ set({ planContent }, false, "setPlanContent"),
}),
{
name: "conversation-store",
diff --git a/frontend/src/types/v1/core/base/base.ts b/frontend/src/types/v1/core/base/base.ts
index 30c39cec89..7704f1105d 100644
--- a/frontend/src/types/v1/core/base/base.ts
+++ b/frontend/src/types/v1/core/base/base.ts
@@ -6,7 +6,8 @@ type EventType =
| "Terminal"
| "FileEditor"
| "StrReplaceEditor"
- | "TaskTracker";
+ | "TaskTracker"
+ | "PlanningFileEditor";
type ActionOnlyType =
| "BrowserNavigate"
diff --git a/frontend/src/types/v1/core/base/observation.ts b/frontend/src/types/v1/core/base/observation.ts
index 0625c9d336..062d7ddf6e 100644
--- a/frontend/src/types/v1/core/base/observation.ts
+++ b/frontend/src/types/v1/core/base/observation.ts
@@ -190,6 +190,38 @@ export interface TaskTrackerObservation
task_list: TaskItem[];
}
+export interface PlanningFileEditorObservation
+ extends ObservationBase<"PlanningFileEditorObservation"> {
+ /**
+ * Content returned from the tool as a list of TextContent/ImageContent objects.
+ */
+ content: Array<TextContent | ImageContent>;
+ /**
+ * Whether the call resulted in an error.
+ */
+ is_error: boolean;
+ /**
+ * The commands to run. Allowed options are: `view`, `create`, `str_replace`, `insert`, `undo_edit`.
+ */
+ command: "view" | "create" | "str_replace" | "insert" | "undo_edit";
+ /**
+ * The file path that was edited.
+ */
+ path: string | null;
+ /**
+ * Indicates if the file previously existed. If not, it was created.
+ */
+ prev_exist: boolean;
+ /**
+ * The content of the file before the edit.
+ */
+ old_content: string | null;
+ /**
+ * The content of the file after the edit.
+ */
+ new_content: string | null;
+}
+
export type Observation =
| MCPToolObservation
| FinishObservation
@@ -199,4 +231,5 @@ export type Observation =
| TerminalObservation
| FileEditorObservation
| StrReplaceEditorObservation
- | TaskTrackerObservation;
+ | TaskTrackerObservation
+ | PlanningFileEditorObservation;
diff --git a/frontend/src/types/v1/type-guards.ts b/frontend/src/types/v1/type-guards.ts
index e73a5e0e74..306661e854 100644
--- a/frontend/src/types/v1/type-guards.ts
+++ b/frontend/src/types/v1/type-guards.ts
@@ -5,6 +5,7 @@ import {
ExecuteBashAction,
TerminalAction,
ExecuteBashObservation,
+ PlanningFileEditorObservation,
TerminalObservation,
} from "./core";
import { AgentErrorEvent } from "./core/events/observation-event";
@@ -116,6 +117,15 @@ export const isExecuteBashObservationEvent = (
(event.observation.kind === "ExecuteBashObservation" ||
event.observation.kind === "TerminalObservation");
+/**
+ * Type guard function to check if an observation event is a PlanningFileEditorObservation
+ */
+export const isPlanningFileEditorObservationEvent = (
+ event: OpenHandsEvent,
+): event is ObservationEvent<PlanningFileEditorObservation> =>
+ isObservationEvent(event) &&
+ event.observation.kind === "PlanningFileEditorObservation";
+
/**
* Type guard function to check if an event is a system prompt event
*/