OpenHands/AGENTS.md

Repository Notes

General

• This repository is a near-direct port of the OpenHands frontend, adapted to talk straight to software-agent-sdk / agent_server without the usual OpenHands app backend.
• Frontend API adaptation lives mainly in src/api/:
  • option-service fabricates an OSS web-client config and reads models/providers through @openhands/typescript-client LLM endpoints.
  • settings-service uses @openhands/typescript-client settings APIs for persistence; reads schemas from /api/settings/agent-schema and /api/settings/conversation-schema, fetches settings with optional X-Expose-Secrets: encrypted header for conversation start payloads, and saves settings via PATCH with diffs.
  • agent-server-conversation-service, event-service, agent-server-git-service, and skills-service route local agent-server access through @openhands/typescript-client rather than direct HTTP calls.
• Supported env vars for deployment:
  • VITE_BACKEND_BASE_URL for the agent server base URL.
  • VITE_SESSION_API_KEY for optional session auth.
  • VITE_WORKING_DIR for the default workspace path sent when starting conversations.
  • VITE_WORKER_URLS as a comma-separated list of browser worker URLs if you want the Browser tab to probe exposed app hosts.
  • VITE_ENABLE_BROWSER_TOOLS=false to omit BrowserToolSet from new conversation payloads.
  • VITE_LOAD_PUBLIC_SKILLS=false to disable loading public skills from the OpenHands extensions marketplace (https://github.com/OpenHands/extensions). Defaults to true.
• Default working-dir fallback is now the relative path workspace/project (exported as DEFAULT_WORKING_DIR from src/api/agent-server-config.ts); git-path heuristics and the default PLAN preview path should reuse that constant instead of hardcoding /workspace/project.
• The UI keeps most OpenHands routes/layout intact, but hosted-only behavior (org, account management, integrations) has been removed via the fabricated OSS config because there is no separate app backend.
• Verification command: npm run typecheck && npm run build.
• GitHub automation now includes .github/workflows/ci.yml for npm ci, npm test, and npm run build, plus .github/dependabot.yml with weekly npm/github-actions updates gated by a 7-day cooldown.

Visual Snapshot Testing

• Snapshot tests live in tests/e2e/snapshots/ and compare screenshots against baselines stored as GitHub Actions artifacts (NOT in git).
• Baseline storage: Baselines are stored as the snapshot-baselines artifact (90-day retention), uploaded on every push to main. They are never committed to the repository — tests/e2e/__snapshots__/ is gitignored. The artifact is found by querying the artifacts API by name (not by workflow run status) so only runs that actually uploaded the artifact are matched.
• Run locally with npm run test:e2e:snapshots; generate/update snapshots with npm run test:e2e:snapshots:update.
• CI workflow (snapshot-tests.yml):
  • On main: Runs test:e2e:snapshots:update, uploads tests/e2e/__snapshots__/ as the snapshot-baselines artifact (90 days).
  • On PRs: Downloads the latest snapshot-baselines artifact, runs test:e2e:snapshots against it, generates current snapshots via test:e2e:snapshots:update, then posts a fresh PR comment (old comment is deleted first so image URLs always point to the current run). Changed snapshots are shown in a side-by-side expected/actual/diff table; new snapshots show the full screenshot. Images are force-pushed to a dedicated snapshot-artifacts/pr-<N> orphan branch (NOT the PR branch) so required CI checks are never invalidated. URLs are raw.githubusercontent.com/<owner>/<repo>/<sha>/changed/... or .../new/.... Triggers: opened, synchronize, reopened, labeled, unlabeled.
  • Force-regenerate baselines: Trigger the Snapshot Tests workflow manually with force_update=true.
• PR comment: tests/e2e/snapshots/scripts/post-snapshot-comment.mjs posts a fresh comment (<!-- snapshot-test-report --> marker) with collapsed <details> sections — 🔴 Changed (side-by-side expected/actual/diff), 🆕 New (full screenshot), ✅ Unchanged (list of names).
• Acknowledging intentional changes: If snapshots changed on purpose (UI redesign, etc.), add the update-snapshots label to the PR. This causes: (1) the CI failure step to be skipped so the check passes, (2) the comment status to flip to ✅ with a note that changes are acknowledged, (3) the labeled trigger fires a fresh CI run automatically so no manual re-run is needed. Removing the label re-enables the failure. When the PR merges, the main-branch run uploads the new screenshots as the updated baseline — no separate "regenerate on main" step required.
• Viewing diffs: On failure, Playwright generates *-actual.png, *-expected.png, and *-diff.png in test-results/. Run npx playwright show-report to view the HTML report. The PR comment also embeds these images directly.
• Bootstrap: When no snapshot-baselines artifact exists on main yet, all snapshots are classified as "🆕 New" and CI passes. The first main-branch run after this state uploads the initial artifact.
• Image branch cleanup: the snapshot-artifacts/pr-<N> branch is deleted automatically by the cleanup-snapshot-artifacts job in pr-artifacts.yml when the PR is closed (merged or abandoned). No manual cleanup needed.
• Key patterns for writing snapshot tests:
  • Use setupMocks(page, showConsentModal) helper to configure API mocks consistently.
  • Use dismissConsentModal(page) after navigation to dismiss the analytics modal.
  • Use animations: "disabled" and maxDiffPixelRatio: 0.01 in toHaveScreenshot() to reduce flakiness.
  • Target specific elements via page.getByTestId() rather than full-page screenshots when possible.
  • Hidden checkbox pattern: SettingsSwitch renders <input hidden data-testid="...">. Both toBeVisible() and click({ force: true }) fail on hidden inputs (no layout dimensions). Use the enclosing <label>: page.locator('label:has([data-testid="my-toggle"])').click() — the browser's label→control activation fires onChange on the hidden input.
  • HeroUI Autocomplete testId forwarding: Autocomplete does NOT forward data-testid to any DOM element. Use getByRole("combobox", { name: /label text/ }) to locate/assert on dropdown fields generated by SchemaField.
  • SdkSectionPage early return: SdkSectionPage returns a plain <p> (no data-testid wrapper) when filteredSchema.sections.length === 0. Always ensure the mock schema includes the section the page requests. The condenser section is in agent_settings_schema (default source), not conversation_settings_schema.
• Composing tests: Use test.step() for iterative snapshots within a single test, or extract helper functions (like navigateToSettings(page)) to share setup across tests. For heavier reuse, use Playwright fixtures via test.extend().
• Snapshots are organized by {snapshotDir}/{testFilePath}/{projectName}/{arg}.png (configured in playwright.config.ts).
• Conversation page snapshot tests: The dev server uses MSW service workers for API mocking. For conversation-page tests, rely on MSW's pre-defined mock conversations (IDs "1", "2", "3" in src/mocks/conversation-handlers.ts) rather than fighting Playwright route interception. MSW's service worker intercepts requests before Playwright page.route() can; Playwright route interceptors only see requests that escape the service worker. Stub WebSocket via page.addInitScript() and inject events into the Zustand store via the exposed window.__OH_EVENT_STORE__ API. Use test.describe.configure({ mode: "serial" }) for conversation tests since the WebSocket stub + heavier page setup can cause intermittent failures in parallel mode.
• Baseline generation for CI: Baselines generated locally will NOT match CI (different OS, fonts, rendering). Baselines are regenerated automatically on every push to main. After adding new snapshot tests, open a PR — the new snapshots will be shown as "🆕 New" in the PR comment and become the baseline when the PR merges. To force-refresh baselines from main without waiting for a code push, trigger the "Snapshot Tests" workflow manually with force_update=true.
• MSW handler state is PAGE-level JS, not service-worker state: In MSW 2.x browser mode the request handlers (including mutable Maps like automations) are compiled into the client bundle and run in the main thread. page.reload() re-initialises all module-level state (e.g. const automations = new Map(...) runs fresh on every page load). Tests that need to show an "empty list" state must NOT call page.reload() after deleting items. Instead: make the DELETE fetches from page.evaluate() (which DO go through MSW), then call window.__TEST_INVALIDATE_QUERIES__() (exposed in mock mode by entry.client.tsx) to trigger React Query's cache invalidation in-place without a reload. Example: the automations empty-state snapshot test in tests/e2e/snapshots/automations.snapshot.spec.ts.

Live End-to-End Test Framework

• The live QA path is intentionally separate from ordinary mocked Playwright coverage. If ordinary browser tests are added, keep them outside tests/e2e/live/ so playwright.config.ts can run them while ignoring **/live/**; live LLM-backed tests must never run as part of npm run test:e2e.
• Live tests live under tests/e2e/live/ and are run only through npm run test:e2e:live, which uses playwright.live.config.ts. Keep the spec names descriptive; the primary conversation smoke test is tests/e2e/live/real-agent-server-conversation.spec.ts.
• npm run test:e2e:live loads .env through Node's --env-file-if-exists flag and invokes tests/e2e/live/scripts/run-live-e2e.mjs. The runner validates the required local environment, explains missing credentials/prerequisites, and then runs playwright test --config=playwright.live.config.ts. Use npm run test:e2e:live -- --check to validate local setup without running the test, and pass Playwright flags after -- (for example npm run test:e2e:live -- --headed).
• Local live E2E requires one LLM credential: LIVE_E2E_LLM_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, or LLM_API_KEY. Optional overrides are LIVE_E2E_LLM_BASE_URL, LIVE_E2E_LLM_MODEL, LIVE_E2E_SESSION_API_KEY, LIVE_E2E_BACKEND_URL, and LIVE_E2E_FRONTEND_PORT. The local runner prints which variables are missing without printing secret values.
• Live-test-only helpers belong under tests/e2e/live/utils/. The current helper module is tests/e2e/live/utils/agent-server-conversation.ts; do not put live-only helpers in the shared tests/e2e/support/ directory.
• playwright.live.config.ts starts the real local Agent Server/UI stack via npm run dev:minimal, not MSW mocks. It uses LIVE_E2E_SESSION_API_KEY when set, otherwise generates a per-run random session key and passes it through SESSION_API_KEY, OH_SESSION_API_KEYS_0, and VITE_SESSION_API_KEY; specs that need direct backend requests must inject X-Session-API-Key only for the configured backend origin through routeBackendSessionApiKey(page), never through global Playwright extraHTTPHeaders. Live tests default to frontend port 3101 and Agent Server http://127.0.0.1:18100 so they do not accidentally reuse a normal local dev stack.
• tests/e2e/live/utils/agent-server-conversation.ts configures the running Agent Server before each live conversation by PATCHing ${LIVE_E2E_BACKEND_URL ?? "http://127.0.0.1:18100"}/api/settings with LLM settings and low-risk conversation settings. LLM credentials are read from LIVE_E2E_LLM_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, or LLM_API_KEY; CI defaults use LIVE_E2E_LLM_BASE_URL (default https://llm-proxy.app.all-hands.dev) and LIVE_E2E_LLM_MODEL (default openhands/claude-haiku-4-5-20251001).
• The live conversation test should stay cheap and as deterministic as possible while still exercising one real tool call: it asks the model to run the exact EXPECTED_BASH_COMMAND, waits for the bash output token to appear outside the user's message in the UI, confirms a successful ExecuteBashObservation/TerminalObservation through the real Agent Server events API, and then waits for the final EXPECTED_REPLY_TOKEN. This exercises the real UI, Agent Server settings API, conversation creation, websocket/event path, terminal tool execution, and LLM response path. Because LLM behavior is not perfectly deterministic even at temperature 0, CI keeps one retry for live E2E; future live tests should document any expected variance and avoid prompts that require unnecessary formatting obedience.
• Live E2E must not pollute analytics. playwright.live.config.ts starts the app with VITE_DO_NOT_TRACK=1; the live helper seeds local storage with telemetry/analytics opt-out values before app code runs; and each live spec should install guardAgainstPostHogRequests(page) before navigation so any attempted request to *.posthog.com or z.openhands.dev is blocked locally and fails the test.
• Live Playwright videos are intentionally recorded for PR QA debugging when LIVE_E2E_RECORD_VIDEO=on is set by CI; local default video mode is retain-on-failure. Do not add live tests that render API keys, tokens, secret values, or credential-bearing error messages in the browser. Screenshots should target a safe app/chat region such as data-testid="chat-interface" instead of page.screenshot({ fullPage: true }), and should apply getLiveArtifactMask(page) for text/field redaction; if a future live test must exercise sensitive UI, change that test/media path to redact the sensitive output or retain video only on failure.
• .github/workflows/ci.yml runs live E2E only at PR level: either manually via workflow_dispatch with a required pr_number, or from a same-repository PR carrying the live-e2e label. The live job must skip fork PRs before checking out PR code so LLM credentials and artifact-push tokens are never exposed to untrusted code. Do not broaden it to run on every PR push unless cost and credential policy are explicitly revisited.
• Keep live E2E secrets out of job-level env. The workflow should check whether credentials exist before checkout, but inject the LLM key only into the trusted step that actually runs the live test.
• The live job uploads the Playwright HTML report plus screenshot/video output as a GitHub Actions artifact, and also extracts the primary screenshot/video attachments. It converts the WebM recording to a GIF preview with ffmpeg so GitHub PR comments can inline the preview. Keep Playwright trace capture disabled for live tests because the setup flow sends LLM credentials to the Agent Server settings API, and traces can record request bodies. Failure messages around live Agent Server settings must not print response bodies from credential-bearing requests.
• Inline PR-comment media is stored as PR-only files under .pr/live-e2e/<github_run_id>/ on the PR branch, not on a long-lived orphan media branch. The comment uses raw.githubusercontent.com/<repo>/<artifact_commit>/.pr/live-e2e/... URLs for the GIF and PNG so GitHub can render them inline. The WebM is linked as the full recording because GitHub comments do not reliably inline WebM.
• .github/workflows/pr-artifacts.yml owns two cleanup responsibilities: (1) .pr/live-e2e/ — comments when .pr/ artifacts exist and removes them after PR approval for same-repo PRs (fork PRs require manual cleanup); (2) snapshot-artifacts/pr-<N> — deletes the snapshot image orphan branch when the PR is closed (merged or abandoned), via the cleanup-snapshot-artifacts job triggered on pull_request: [closed].
• The live reporting scripts live beside the live tests under tests/e2e/live/scripts/: run-live-e2e.mjs, extract-live-e2e-media.mjs, render-live-e2e-report.mjs, and upsert-pr-comment.mjs. Keep report/comment/local-runner logic there rather than in top-level scripts/, because these scripts are part of the live E2E framework.
• When changing any part of this framework — live workflow triggers, artifact publishing, .pr cleanup, live Playwright config, live test file layout, helper locations, local runner behavior, or report/comment scripts — update this AGENTS.md section in the same PR so future agents have the current operating model.

Additional Notes

• Direct dependencies and devDependencies in package.json are exact-pinned (no caret ranges); reproducible installs should use the committed package-lock.json plus npm ci, and targeted transitive fixes still belong in overrides.

• package-lock.json must also retain the optional peer entry for node_modules/vite-tsconfig-paths/node_modules/typescript@5.9.3; without that nested lock entry, clean npm ci installs on CI fail with Missing: typescript@5.9.3 from lock file.

• npm test now runs npm run make-i18n first so clean environments generate src/i18n/declaration.ts before Vitest loads aliased imports.

• __tests__/vite-config.test.ts should import vite.config directly under // @vitest-environment node; spawning plain node -e 'import ./vite.config.ts' is not portable across Node patch releases in CI.

• vitest.setup.ts must guard DOM-specific globals (HTMLCanvasElement, HTMLElement, window) because some suites run in the Node environment instead of jsdom.

• __tests__/components/providers/posthog-wrapper.test.tsx must wrap PostHogWrapper in a QueryClientProvider; the wrapper now reads its client from React Query context instead of importing the global singleton.

• WebSocket hook regression note: __tests__/hooks/use-websocket.test.ts's onClose callback assertion was flaky against the shared MSW websocket server in CI; keep that single test on a deterministic stubbed WebSocket close path instead of relying on MSW close timing.

• Library i18n regression note: __tests__/i18n/library-namespace.test.ts imports ../../src/index, which can take >5s under the full Vitest suite after vi.resetModules(). Keep an explicit per-test timeout (currently 15s) so the suite doesn't fail on slow workers.

• src/components/shared/buttons/styled-tooltip.tsx should keep HeroUI tooltip animations disabled in Vitest (disableAnimation when import.meta.env.MODE === "test"); otherwise full-suite runs can end with unhandled window is not defined rejections from framer-motion after jsdom teardown (seen via recent-conversation tests in CI).

• __tests__/i18n/library-namespace.test.ts imports the full library entry and can exceed Vitest's default 5s timeout under full-suite load; keep an explicit higher timeout on that case unless the test is substantially narrowed.

• @openhands/typescript-client is currently pinned to commit ef62e82fc3dfb03991a1c8025429caf354427263 because the package metadata needed by this PR has not been published as a consistent npm/tagged release yet. That commit ships the needed typed clients plus subpath exports for client/http-client, events/remote-events-list, and workspace/remote-workspace. RemoteWorkspace.gitChanges/gitDiff accept an optional { ref } option; agent-canvas passes 'HEAD' so the changes panel reflects working-tree + index versus the latest commit (i.e. staged + unstaged) instead of a diff against the upstream/default branch.

• The @openhands/typescript-client git dep must be expressed as a git+https://github.com/... URL in both package.json and the top-level dep entry of package-lock.json; the github:OpenHands/... shorthand normalizes to git+ssh:// inside the lockfile, and Vercel's build environment has no GitHub SSH key, so an ssh-pinned lockfile makes Vercel fall back to a stale cached tarball and the bundler then fails with [MISSING_EXPORT] ConversationClient/FileClient/SharedClient is not exported by .../dist/clients.js. scripts/vercel-install.sh (wired up via vercel.json's installCommand) defensively rewrites any leftover git+ssh://git@github.com/ resolved URLs to git+https://github.com/ and adds matching git config --global url..insteadOf aliases before invoking npm ci, so a future regression that re-introduces an ssh-pinned lockfile entry still builds on Vercel. See GitHub issue #384 for the original failure and PR #382 for the prior single-shot lockfile fix that this generalizes.

• Use @openhands/typescript-client classes directly for agent-server-backed REST/workspace/event/VS Code calls. Centralize host/session API key/working-directory option assembly through src/api/agent-server-client-options.ts; the backend fallback policy itself lives in src/api/backend-registry/active-store.ts.

• Local verification/build gotchas:

  • npm run typecheck assumes generated translation types exist; run npm run make-i18n first if src/i18n/declaration.ts is missing.

• Merge note: main removed the old project-management integration subcomponents/hooks and their related feature-flag/i18n surface. If a feature branch still keeps the top-level /integrations git-token page, retain src/routes/git-settings.tsx plus the git-provider token inputs/hooks, but do not blindly restore src/components/features/settings/project-management/* or the old integration mutation/query hooks unless the corresponding option types and i18n keys are also reintroduced.

• The OSS cleanup removed hosted-only auth, org, account, onboarding, and invitation codepaths, routes, and tests. Keep integrations, git-settings, secrets, MCP settings, and other local/self-hosted flows intact when simplifying OSS behavior.

• When merging main into this branch, keep the new agent-server compatibility bootstrap in src/root.tsx, but do not reintroduce hosted-only invitation cleanup or marketing CTA chrome in the OSS user menu; the OSS account menu should just render settings links plus Docs.

• During the OSS cleanup audit, the runtime removals held up, but route-level regression coverage for still-active OSS settings pages had been deleted too aggressively. Keep focused tests for local/self-hosted screens like app-settings, llm-settings, git-settings, mcp-settings, and secrets-settings even when stripping hosted-only code.

• npm run dev:mock needs MSW handlers for the direct agent-server routes used by the adapted frontend, not the original OpenHands mock paths. Key routes that must stay covered are:

  • bootstrap/model loading: /server_info, /api/llm/models/verified, /api/llm/providers
  • settings schemas: /api/settings/agent-schema, /api/settings/conversation-schema
  • settings CRUD: GET /api/settings, PATCH /api/settings
  • secrets CRUD: GET /api/settings/secrets (list), GET /api/settings/secrets/:name (value), PUT /api/settings/secrets (upsert), DELETE /api/settings/secrets/:name
  • conversation browsing/loading: /api/conversations/search, /api/conversations?ids=..., /api/conversations/:id, /api/conversations/:id/events/*
  • runtime git panels: /api/git/changes, /api/git/diff

• Static mock verification needs a build created with VITE_MOCK_API=true (use npm run build:mock); the client must start MSW whenever that flag is enabled, even in production/static builds, otherwise routes like /settings and the conversations pane fall through to the static server and crash on undefined .filter/.map assumptions.

• No frontend version guard: OptionService.getConfig() calls loadAgentServerInfo() which fetches /server_info only to (a) detect an unreachable agent server (renders the onboarding screen via AgentServerUnavailableError) and (b) cache usable_tools for tool gating. All advertised versions are accepted. The "manage backends" modal displays each local backend's /server_info.version in light text via the BACKEND$VERSION_LABEL translation key.

• Backend registry: there is no longer a separate "bundled" backend. On first read of the openhands-backends localStorage key (raw === null), readStoredBackends() seeds the registry with one default local backend (makeDefaultLocalBackend(), id BUNDLED_BACKEND_ID = "default-local", host/api-key from agent-server-config). After that the seed is just an ordinary registered backend — users can rename or remove it like any other. getEffectiveLocalBackend() returns the first registered local, falling back to a synthesized default if the registry has no locals (used by API clients that need a baseline local target). The "Manage backends" modal and the BackendSelector dropdown both read from the single registered list, so the seeded default appears in both without any special-casing.

• Shared Dropdown open behavior: when the menu opens, it clears the input/search text so callers can show the current selection via placeholder while still rendering the full option list. Generic dropdown tests should not expect the selected label to remain in the input after reopening unless the parent explicitly controls that display.

• useLoadOlderEvents needs ref-based isLoading / hasMore guards in addition to React state because ChatInterface can trigger pagination from onScroll, onWheel, and the no-overflow effect in the same tick; closure-based state alone allows duplicate page requests.

• ChatInterface continuity tests should assert that conversation messages render without the full chat-messages-skeleton, not that data-testid="loading-spinner" is absent: the lazy older-events indicator reuses the shared LoadingSpinner component and legitimately renders that inner test id while history backfill is running.

• useConversationHistory now mirrors the older-events pagination fallback when the first page is exactly INITIAL_HISTORY_PAGE_SIZE: treat next_page_id or a full page as hasMore, so older agent-server variants that omit next_page_id still allow one more backfill request. The hook and useLoadOlderEvents also defensively reject mocked/malformed page.items responses before reversing them.

• /server_info tool capability metadata from software-agent-sdk PR #3028 ended up shipping as usable_tools (not available_tools). Frontend browser-tool gating should key off usable_tools, and still default to allowing tools when the server does not advertise tool metadata.

• Useful regression tests for mock mode live in __tests__/api/option-service.test.ts, __tests__/api/mock-conversation-handlers.test.ts, and __tests__/api/mock-settings-handlers.test.ts.

• Browser-verified mock-mode tour artifact was generated at artifacts/frontend-tour.gif.

• Live agent_server compatibility quirks discovered during browser verification:

  • Latest openhands-agent-server live-mode notes (verified against 1.18.1):
    • /api/settings/agent-schema and /api/settings/conversation-schema exist on recent servers, but they return 401 when the server was started with SESSION_API_KEY or OH_SESSION_API_KEYS_0; the frontend must send the same value as VITE_SESSION_API_KEY / X-Session-API-Key.
    • The provider/model picker should use /api/llm/providers, /api/llm/models, and /api/llm/models/verified; /api/v1/config/providers/search and /api/v1/config/models/search 404 on current live agent-server releases.
    • When the browser is accessing the frontend through a remote host (for example an All Hands work URL) but VITE_BACKEND_BASE_URL points at 127.0.0.1/localhost, browser-side REST calls must fall back to the frontend origin so Vite can proxy /api and /sockets to the local backend.
  • GET /api/conversations expects repeated ids params (?ids=a&ids=b), not Axios's default bracket form (ids[]=a), so the shared Axios client needs a custom params serializer.
  • Runtime git panels should prefer the conversation's reported workspace.working_dir when present; falling back to /workspace/project can produce 500s like Not a git repository for direct local workspaces such as /workspace/project/agent-canvas.
  • For development, npm run dev now uses uvx to run a temporary agent-server installation, so no permanent uv tool install is required. For standalone installations, uv tool install -U --with openhands-tools --with openhands-workspace openhands-agent-server would expose the executable as agent-server (not openhands-agent-server), possibly requiring ~/.local/bin on PATH.
  • Current SDK / agent-server conversation start payloads must use SDK-registered snake_case tool names, not the old class-style names. Working names against SDK v1.18.1 were:
    • terminal
    • file_editor
    • task_tracker
    • browser_tool_set Using TerminalTool / FileEditorTool / TaskTrackerTool / BrowserToolSet caused live /api/conversations/{id}/events runs to fail with ToolDefinition '<name>' is not registered.
  • The root compatibility bootstrap now treats /server_info network/timeout failures as a first-class AgentServerUnavailableError, uses a short 5s timeout for that probe, and disables React Query retries/toasts for the initial config fetch so missing backends fail fast with an explicit full-screen notice.
  • For local verification in this repo, setting VITE_WORKING_DIR=/workspace/project/agent-canvas avoids initial Changes-tab 500s from pointing conversations at the non-repo parent /workspace/project.
  • A successful end-to-end live run in this environment required a real LLM config (LLM_MODEL + LLM_API_KEY). The default litellm_proxy/... model with no llm_api_key failed at runtime with a litellm.AuthenticationError.

• Agent-server recovery UX gotchas:

  • Keep /settings/agent-server in the intermediate-page bypass path (use-is-on-intermediate-page) so useConfig()-driven layout/sidebar queries do not block the recovery screen behind a global spinner.
  • PostHogWrapper should treat config-fetch failures as silent/optional (no user-facing toast), otherwise onboarding/recovery screens show a duplicate incompatible-server toast on top of the friendly guidance.
  • Keep the settings route on the compact AgentServerConnectionForm variant with showSectionHeader={false} and no checklist; the blocked root onboarding should stay similarly minimal, with only the status card plus a single sentence that links to the repo setup instructions.
  • For local screenshot/GIF capture of SPA routes, serve build/ with an SPA fallback (for example sirv build --single) and restart the static server after each rebuild so hashed asset URLs stay in sync.

• Git provider token persistence note: src/api/secrets-service.ts stores git provider tokens in TWO places:

  1. Agent-server secrets API (PUT /api/settings/secrets) with naming convention GIT_PROVIDER_{PROVIDER}_TOKEN - for agent runtime use
  2. localStorage (openhands-agent-server-git-provider-tokens) - for frontend git API calls (repo search, branches, etc.) The addGitProvider method stores to server FIRST (must succeed), then updates localStorage. This ensures server-side persistence is the source of truth.

• Agent server connection settings now live at Settings > Agent Server (/settings/agent-server). The page reads deployment defaults from VITE_BACKEND_BASE_URL / VITE_SESSION_API_KEY, saves user overrides in the openhands-agent-server-config localStorage key, and must stay reachable even when the backend compatibility probe fails so users can recover from missing or wrong backend configuration.

• Backend/footer actions that launch modals from inside a dropdown or popover should intercept onMouseDown to keep the menu mounted, then perform the actual open on onClick. Current examples: Add backend / Manage backends in src/components/features/backends/backend-selector.tsx, plus the mirrored workspace-footer buttons in src/components/features/conversation-panel/new-conversation-button.tsx.

• BackendSelector's cloud-org switch paths should never rethrow from the dropdown onChange handler: unexpected non-Axios failures need a generic error toast instead of an unhandled promise rejection, and the malformed (cloud backend, null org) self-heal path should fall back to the bundled backend if /switch fails.

• NewConversationButton should support keyboard dismissal (Escape) for its inline popover, while still keeping the popover open when its modal children (FolderBrowserModal, ManageWorkspacesModal) are active.

• README expectation: keep the first section as a concrete, chronological from-scratch quickstart for running this frontend against a real openhands-agent-server (clone, install prerequisites, optional .env, run npm run dev:docker or npm run dev:dangerously-dockerless).

• Keep README user-focused and move contributor/developer-specific workflows (dev:safe, mock mode, detailed env vars/build-test notes) into DEVELOPMENT.md.

• scripts/dev-safe.mjs uses uvx for temporary agent-server installation — no permanent uv tool install needed. Environment variables (highest precedence first):

  • OH_AGENT_SERVER_LOCAL_PATH — absolute path to a local software-agent-sdk checkout. Runs the local checkout via uvx with --with-editable for openhands-sdk/openhands-tools/openhands-workspace and --reinstall for openhands-agent-server, so SDK edits are picked up on restart. Highest precedence.
  • OH_AGENT_SERVER_GIT_REF — git commit SHA or branch name (takes precedence over version)
  • OH_AGENT_SERVER_VERSION — specific PyPI version (e.g., "1.22.1")
  • OH_SECRET_KEY — secret key for settings encryption; uses a static default for local dev since it's needed for reading persisted encrypted values across restarts
  • SESSION_API_KEY / OH_SESSION_API_KEYS_0 / VITE_SESSION_API_KEY — session API key for agent-server authentication; auto-generated using crypto.randomBytes(32) if not set, passed to both agent-server (OH_SESSION_API_KEYS_0) and frontend (VITE_SESSION_API_KEY)
  • Default: released PyPI version 1.22.1 for agent-server SDK libraries

• scripts/dev-docker.mjs runs the agent-server inside a Docker container instead of via uvx, and serves a static frontend build by default for stable user/tunnel access. Use npm run dev:docker:dynamic or node scripts/dev-docker.mjs --dynamic for the Vite dev server. The default image uses versioned release tags:

  • DEFAULT_AGENT_SERVER_TAG — uses format {version}-python (e.g., 1.22.1-python) for reproducibility. Note: the SDK build script strips the "v" prefix from semver release tags.
  • Should stay in sync with DEFAULT_AGENT_SERVER_VERSION in dev-safe.mjs for consistency between Docker and non-Docker dev modes
  • OH_AGENT_SERVER_GIT_REF — override to use a git ref-based tag (e.g., main → main-python, abc1234 → abc1234-python)
  • Docker images are published from https://github.com/OpenHands/software-agent-sdk via the Agent Server workflow to ghcr.io/openhands/agent-server
  • The container runs as the host UID/GID when Node exposes process.getuid() / process.getgid(). In the default isolated-home mode, /home/openhands is a writable tmpfs and persistence remains at /home/openhands/.openhands, so host-owned bind mounts remain writable without persisting ordinary home cache/config files.

• Security: scripts/dev-safe.mjs and scripts/dev-with-automation.mjs auto-generate random API keys when needed and persist the defaults so static builds, localStorage, and restarted services stay in sync:

  • SESSION_API_KEY — 64-character hex (256-bit) for agent-server API authentication; persisted at ~/.openhands/agent-canvas/session-api-key.txt unless overridden via env var
  • AUTOMATION_LOCAL_API_KEY — 64-character hex for automation backend auth; persisted at ~/.openhands/agent-canvas/automation-api-key.txt unless overridden
  • OH_SECRET_KEY — kept as a static default because it's used for encrypting/decrypting persisted settings values and needs consistency across restarts

• scripts/dev-safe.mjs should fail fast if uvx cannot be spawned (for example missing PATH entries).

• npm run dev now runs the Docker full stack with automation and a static frontend by default (via dev:docker). npm run dev:dangerously-dockerless does the same without Docker through the dev-static.mjs launcher. Use npm run dev:docker:dynamic or npm run dev:dangerously-dockerless:dynamic for Vite/HMR.

• scripts/dev-with-automation.mjs runs the full stack: agent-server, automation backend (both via uvx), frontend server, and ingress proxy. It defaults to Vite when run directly, supports --static for an existing build, and supports --dynamic so wrappers that default static can opt back into Vite. Uses a standalone ingress proxy (scripts/ingress.mjs) to route traffic:

  • /api/automation/* → automation backend (:18001)
  • /api/*, /sockets, etc. → agent server (:18000)
  • /* (default) → frontend server (:3001), either Vite or static depending on launcher mode
  • Environment variables: PORT (ingress port, default: 8000), OH_AUTOMATION_GIT_REF (git ref, overrides default version), OH_AUTOMATION_VERSION (default: 1.0.0a2), AUTOMATION_LOCAL_API_KEY (optional, use a fixed key; default: persisted generated key), OH_AUTOMATION_API_KEY_PATH (override the persisted default key path)
  • scripts/check-sdk-version-sync.mjs checks the released openhands-automation package against DEFAULT_AUTOMATION_SDK_VERSION in scripts/dev-with-automation.mjs; that value may intentionally lag DEFAULT_AGENT_SERVER_VERSION while automation has not yet published a matching release.
  • Access points: http://localhost:8000/ (main UI), http://localhost:8000/api/automation/docs (API docs)
  • Security: AUTOMATION_LOCAL_API_KEY defaults to a generated key persisted across restarts because static frontend builds bake it into VITE_AUTOMATION_API_KEY. Set the env var explicitly to rotate or pin it. The cipher key (OH_SECRET_KEY) keeps a static default for local dev since it's used for encrypting/decrypting persisted settings values.

• scripts/ingress.mjs is a standalone HTTP reverse proxy that can be used independently to route traffic to multiple backends based on URL path prefix.

• scripts/dev-safe.mjs (now npm run dev:minimal) runs just agent-server + Vite without automation.

• Vite dev mode can black-screen on first load with 504 Outdated Optimize Dep if core client-entry deps are not prebundled; keep react, react/jsx-runtime, react-dom/client, and react-router/dom in optimizeDeps.include.

• Bundle/dev-graph hygiene (Tier 1 cleanup landed):

  • src/i18n/translation.json (~1 MB) is imported only by src/i18n/resources.ts, which src/i18n/index.ts re-exports as translationResources for the @openhands/agent-canvas/i18n subpath. The re-export is a export … from plus /* @__PURE__ */ annotation, so rollup drops the JSON from the app build (the prod custom-toast-handlers chunk went from ~909 KB to ~74 KB). Do not move the JSON import back into src/i18n/index.ts — that immediately re-bundles all translations into every chunk that imports i18n.
  • The environment-switch overlay is split: lightweight store/triggers live in components/features/backends/environment-switch-store.ts; the React component lives in environment-switch-overlay.tsx (re-exports the store API for back-compat). Eagerly-mounted callers (e.g. backend-selector.tsx) MUST import trigger helpers from the store, not the overlay file. The overlay is React.lazy'd from routes/root-layout.tsx.
  • Other always-conditional UI is React.lazy'd to keep the root layout's eager graph small: AnalyticsConsentFormModal, AlertBanner (root-layout), SettingsModal (sidebar), AgentServerConnectionForm (root.tsx). Tests that assert on these mounted nodes need await screen.findByTestId(...) instead of getByTestId(...).
  • The terminal tab (components/features/terminal/terminal.tsx) is React.lazy'd in conversation-tab-content.tsx alongside the other tabs, so xterm + addon-fit + xterm.css don't enter the conversation route's eager graph.
  • Avoid importing app code through #/components/conversation-events/chat or its event-message-components/index.ts barrel — they exist for lib/index.ts (npm subpath) consumers only. Internal callers use deep paths (./messages, ./event-message-components/<name>, ./event-content-helpers/should-render-event) so Vite dev doesn't fan out the barrel.

• Vercel deployment note: React Router builds for this repo must keep build/client intact on actual Vercel builds and include presets: [vercelPreset()] from @vercel/react-router/vite; flattening build/client during a Vercel build produces deployments with empty outputs (routes: null, no static files) and a production 404.

• The repo should include a root LICENSE file to satisfy the incubator-program requirements.

• OpenHands repo bootstrap files live under .openhands/:

  • .openhands/setup.sh installs uv (via curl -LsSf https://astral.sh/uv/install.sh | sh) if not present, installs frontend dependencies with npm ci when needed, creates .env from .env.sample if missing, appends VITE_WORKING_DIR for this repo when unset, and generates src/i18n/declaration.ts via npm run make-i18n.
  • .openhands/hooks.json registers .openhands/hooks/on_stop.sh as a Stop hook so OpenHands runs the local quality gate (npm run lint and npm test) before finishing.

• GitHub PR-review automation should stay aligned with the current OpenHands repo conventions: keep the review workflow at .github/workflows/pr-review-by-openhands.yml, keep the companion .github/workflows/pr-review-evaluation.yml, auto-run on newly opened non-draft PRs and ready_for_review events from established contributors, still support the review-this label / openhands-agent / all-hands-bot reviewer triggers, use the OpenHands app LLM proxy defaults, and use the dual-trigger pattern (pull_request for same-repo PRs, pull_request_target for forks) so workflow changes can self-verify without widening fork secret exposure.

• The repo now includes .agents/skills/custom-codereview-guide.md, adapted from OpenHands/software-agent-sdk, to force PR reviews to always leave either an APPROVE or COMMENT review instead of silently finishing with no review object.

• HeroUI rollback / migration notes:

  • The attempted HeroUI v3 upgrade changed global theme wiring and homepage design tokens enough that the repo currently prefers @heroui/react@2.8.10 until a broader visual validation pass is done.
  • Keep the v2 Tailwind integration active via @plugin '../hero.ts' in src/tailwind.css and source HeroUI classes from node_modules/@heroui/theme/dist/**/*.
  • The settings UI currently relies on the v2 Autocomplete + AutocompleteItem/AutocompleteSection APIs in settings-dropdown-input.tsx and model-selector.tsx; a future v3 retry will need to replace those controls again.

• Library i18n is now namespace-scoped under openhands: src/i18n/index.ts exports OPENHANDS_I18N_NAMESPACE, translationResources, and waitForI18n(), scripts/make-i18n-translations.cjs emits public/locales/<lang>/openhands.json, standalone src/entry.client.tsx explicitly awaits i18n init, and host apps can register bundles via the @openhands/agent-canvas/i18n subpath export.

• Route decoupling note: src/components/ should stay free of direct react-router imports. Route state now flows through src/context/navigation-context.tsx, the standalone app bridges router state with src/routes/react-router-navigation-provider.tsx, and link-like UI should use src/components/shared/navigation-link.tsx.

• Test helper note: test-utils.tsx now wraps renders with a default NavigationProvider (currentPath: "/", conversationId: "test-conversation-id"). Navigation-sensitive tests can override that via renderWithProviders(..., { navigation: { ... } }).

• CSS isolation for embeddable/hosted use now relies on a scoped wrapper attribute: all bundled CSS is prefixed under [data-agent-server-ui] via postcss-prefix-selector in vite.config.ts, with selector exceptions handled by transformAgentServerUISelector() in src/styles/agent-server-ui-style-scope.ts. That transform must remap global selectors like :root, html, and body directly onto the scoped shell instead of emitting impossible descendants such as [data-agent-server-ui] :root.

• Public embedding entry points should use AgentServerUIProviders (scoped root on by default) or AgentServerUIRoot for manual control. The standalone app already renders its own scoped root in src/root.tsx, so src/entry.client.tsx must pass withStyleRoot={false} to avoid nesting duplicate shells. Keep AgentServerUIRoot and the scoping constants re-exported from src/lib/index.ts so library consumers can customize the host wrapper without reaching into private paths.

• AgentServerUIRoot's themed inner wrapper must set a default color: var(--foreground) in addition to the dark / data-theme markers; otherwise inherited text and currentColor SVG icons fall back to dark browser defaults after CSS scoping, causing dark-on-dark regressions on pages like the home screen.

• Theme/customization tokens for the embedded shell are exposed as --oh-* CSS variables. Override them through styleOverrides, style, or host CSS targeting [data-agent-server-ui]; Tailwind theme tokens in src/tailwind.css should continue to reference those variables with @theme inline so host apps can restyle the UI without reworking component class names.

• Regression coverage for the CSS isolation work lives in __tests__/agent-server-ui-providers.test.tsx, __tests__/agent-server-ui-style-scope.test.ts, and the browser-level tests/e2e/regressions/css-isolation.spec.ts Playwright test.

• Conversation history is loaded lazily, REST-first then WebSocket:

  • useConversationHistory (in src/hooks/query/use-conversation-history.ts) fetches only the most recent INITIAL_HISTORY_PAGE_SIZE (default 50) events using sort_order='TIMESTAMP_DESC', then reverses to chronological order. Older pages are paginated in via useLoadOlderEvents when the user scrolls near the top of the chat.

  • EventService.searchEvents(conversationId, conversationUrl, sessionApiKey, options) returns the raw EventSearchPage ({ items, next_page_id }); options support limit, pageId, sortOrder, timestampGte, timestampLt. Both the local and cloud-proxy code paths forward the new params.

  • The main ConversationWebSocketProvider waits for the REST query to settle before opening its socket, then connects with resend_mode='since' and after_timestamp=<latest preloaded event ts> (falling back to 'all' when the REST result is empty or errored). The legacy resend_all=true flag is removed for the main connection; the planning-agent sub-conversation still uses resend_all until it is migrated to the same REST-then-WS pattern.

  • The event store gained a bulk addEvents(events) action (used for the initial REST seed and for "scroll-up" pagination) that re-sorts by timestamp once at the end so older pages can be merged in cheaply. Per-event dedup still works via the existing eventIds set.

  • ChatInterface wires useLoadOlderEvents into its scroll handler (threshold 80px from the top), shows a data-testid="loading-older-events" spinner during pagination, and preserves the visible scroll offset by storing the previous scrollHeight and adding the height delta after the older page renders.

  • useLoadOlderEvents intentionally distinguishes between "no anchor yet" (empty store before the initial REST seed, so loadOlder() should no-op) and "malformed oldest event" (store has an oldest event with no timestamp, so the hook throws, flips hasMore false, and ChatInterface surfaces the failure via the shared error banner instead of failing silently).

• Action grouping in the chat stream:

  • src/components/conversation-events/chat/group-events.ts folds runs of consecutive groupable events (regular ActionEvent/ObservationEvent cards, but not FinishAction, ThinkAction, PlanningFileEditorObservation, TaskTrackerObservation, hooks, errors, or message events) into single RenderedItem groups. The threshold lives in EVENT_GROUP_MIN_SIZE (currently 2, so even pairs of back-to-back actions get folded).
  • EventGroup (src/components/conversation-events/chat/event-message-components/event-group.tsx) is the collapsible header that wraps each run. Default state is collapsed; the header shows EVENT_GROUP$ACTIONS_COMPLETED (with a success check) when the group is done, or EVENT_GROUP$ACTIONS_PROGRESS plus the currently-running action's title (from getEventContent) while a member ActionEvent has not yet been replaced by its observation in the UI events array. Expanding renders the original EventMessages verbatim so each card still expands the way it did before.
  • Agent thoughts attached to an ActionEvent (event.thought) are hoisted out of groups: groupEvents emits a third RenderedItem kind "thought" whenever a groupable event carries (or, for an observation, originates from) a non-empty thought, flushing the current run and starting a new one. messages.tsx renders that item via ThoughtEventMessage and passes suppressThought to EventMessage so the inline thought isn't duplicated inside the group's expanded content. ThinkAction is excluded from this hoisting because the thought IS its action body and is rendered through its own codepath.
  • groupEvents now de-duplicates hoisted thoughts by action ID so mixed UI arrays that temporarily contain both an action and its replacement observation do not emit the same thought twice; minSize is treated as a validated internal invariant (>= 1).
  • EventGroup should return null for an empty events array and wire the toggle button to the expanded body with aria-controls / role="region" / aria-labelledby.
  • src/components/conversation-events/chat/messages.tsx is the only consumer; the grouping is transparent to upstream code. Coverage lives in __tests__/components/conversation-events/chat/group-events.test.ts (pure logic, including thought hoisting) and __tests__/components/conversation-events/chat/event-message-components/event-group.test.tsx (rendering/interaction).

• Home page workspace UX (agent-server backend):

  • RepoConnector no longer renders a tabbed launcher; it just renders WorkspaceSelectionForm because this build only ever talks to an agent-server backend (no cloud backend is wired up). The old LaunchTabs component was removed; if a cloud backend is ever supported again, branch on backend mode in RepoConnector and render RepositorySelectionForm for that path.
  • FolderBrowserModal's "Use this folder" button adds only the currently navigated directory as a single workspace (named by its basename). It no longer iterates subdirs and adds each child as a separate workspace.
  • The WorkspaceDropdown sticky footer now exposes both "+ Add Workspace" (opens the folder browser) and "Manage Workspaces" (opens ManageWorkspacesModal, which lets users remove individual workspaces via useWorkspacesStore.removeWorkspace). The Manage button is hidden when there are no workspaces yet.
  • The sidebar "+ New Conversation" trigger (NewConversationButton in src/components/features/conversation-panel/) opens a popover that is a flat list, not the home-screen combobox: a leading "No workspace" entry plus one entry per stored workspace, each clicking through to useCreateConversation immediately (no separate Launch button). It mirrors the dropdown footer actions/pattern (+ Add Workspace, Manage Workspaces) locally rather than embedding WorkspaceDropdown itself.
  • useResolvedWorkspaces() now returns isLoading / isError for parent-directory scans; WorkspaceSelectionForm should surface that state (status text and disabling the empty dropdown while parent results are still loading) instead of assuming the merged list is immediately ready.
  • ManageWorkspacesModal should require a confirmation step before removing either a saved workspace or a workspace parent; parent removals should mention the child-workspace impact, and tests should assert both the confirmation flow and that removing the selected workspace clears the launch selection.
  • In useWorkspacesStore, keep clearWorkspaces() scoped to literal workspaces only; use explicit helpers like clearWorkspaceParents() / clearAll() for broader resets so future callers do not accidentally wipe parent registrations.

• Custom secrets are NOT auto-attached by the agent-server. POST /api/conversations only persists what the client sends in request.secrets; the persisted secrets store (/api/settings/secrets) is never read at conversation-start. buildStartConversationRequestWithEncryptedSettings enumerates SecretsService.getSecrets() and turns each entry into a LookupSecret whose url points back at /api/settings/secrets/{name} and whose headers carry X-Session-API-Key for auth. Pre-1.21.x agent-server SDKs would silently drop that header during validation when secrets_encrypted=true (the cipher in the validation context tried to cipher.decrypt(plaintext_session_key), failed, and the validator removed the header — the conversation runtime then got 401s for every saved secret). The SDK fix preserves plaintext header values when decryption fails; if you still see saved secrets unavailable inside a conversation, verify the running agent-server bundles a LookupSecret._validate_secrets that falls back to plaintext on decrypt failure.

• MCP page layout: MCP is a top-level nav entry at /mcp (rendered by src/routes/mcp.tsx), shown right below "Skills" in src/components/features/sidebar/sidebar.tsx. The legacy /settings/mcp route still works as a redirect via src/routes/mcp-settings-redirect.tsx, and src/routes/mcp-settings.tsx re-exports the new page so the published MCPSettings library symbol (in src/components/settings/index.ts) keeps the same shape. Marketplace catalog lives in src/constants/mcp-marketplace.ts (Slack and Tavily must stay first) — src/utils/mcp-marketplace-utils.ts matches installed servers back to catalog entries (Tavily uses the "tavily-builtin" sentinel because it is gated by search_api_key_set rather than mcp_config). Components are colocated under src/components/features/mcp-page/ and reuse the existing MCPServerForm for the "Add custom server" / edit flow.

• Library packaging notes:

  • Public npm entrypoints now come from src/index.ts → src/lib/index.ts, with domain barrels under src/components/{conversation,terminal,browser,files,settings,sidebar}/index.ts.
  • npm run build remains the standalone app build (react-router build), while npm run build:lib runs vite build in library mode plus tsc -p tsconfig.lib.json to emit .d.ts files into dist/.
  • The library build relies on vite.config.ts with BUILD_LIB=true, preserved modules in dist/, and package exports entries that map root/subpaths to dist/**/*.js plus matching declaration files.
  • Declaration emit needs src/library-env.d.ts and the narrowed tsconfig.lib.json; broad src/**/*.tsx declaration builds pulled in route-only files and missed ?react/window globals.

• Bundle/dev-graph hygiene (Tier 1 cleanup landed):

  • src/i18n/translation.json (~1 MB) is imported only by src/i18n/resources.ts, which src/i18n/index.ts re-exports as translationResources for the @openhands/agent-canvas/i18n subpath. The re-export is a export … from plus /* @__PURE__ */ annotation, so rollup drops the JSON from the app build (prod custom-toast-handlers chunk: 909 KB -> 74 KB; conversation chunk: 728 KB -> 392 KB). Do not move the JSON import back into src/i18n/index.ts — that immediately re-bundles all translations into every chunk that imports i18n.
  • The environment-switch overlay is split: lightweight store/triggers live in components/features/backends/environment-switch-store.ts; the React component lives in environment-switch-overlay.tsx (re-exports the store API for back-compat). Eagerly-mounted callers (e.g. backend-selector.tsx) MUST import trigger helpers from the store, not the overlay file. The overlay is React.lazy'd from routes/root-layout.tsx.
  • Other always-conditional UI is React.lazy'd to keep the root layout's eager graph small: AnalyticsConsentFormModal, AlertBanner (root-layout), SettingsModal (sidebar), and the unreachable-backend modal path in root.tsx (ManageBackendsModal). Tests that assert on these mounted nodes may need await screen.findByTestId(...) / waitFor(...) instead of synchronous getByTestId(...).
  • The terminal tab (components/features/terminal/terminal.tsx) is React.lazy'd in conversation-tab-content.tsx alongside the other tabs, so xterm + addon-fit + xterm.css don't enter the conversation route's eager graph (they ship as a separate terminal-*.js chunk now).
  • Avoid importing app code through #/components/conversation-events/chat or its event-message-components/index.ts barrel — they exist for lib/index.ts (npm subpath) consumers only. Internal callers use deep paths (./messages, ./event-message-components/<name>, ./event-content-helpers/should-render-event) so Vite dev doesn't fan out the barrel.

• Backend dropdown connectivity indicator: useBackendsHealth (src/hooks/query/use-backends-health.ts) polls each registered backend every 10s. Local agent-server backends are probed via ServerClient.getServerInfo() (/server_info); cloud SaaS backends are probed via getCurrentCloudApiKey() (/api/keys/current through the bundled /api/cloud-proxy). Verdicts are surfaced as a colored dot rendered through DropdownOption.prefix (added to src/ui/dropdown/types.ts); the trigger reads its prefix from the live options array (not downshift's frozen selectedItem) so the indicator updates without remounting. The same dot is also rendered in each row of ManageBackendsModal, which now opts into a one-shot re-probe for previously disabled backends so opening the modal can clear stale persisted error state when a server has recovered. Tests live in __tests__/hooks/query/use-backends-health.test.tsx, the connection indicator block of __tests__/components/backends/backend-selector.test.tsx, and __tests__/components/backends/manage-backends-modal.test.tsx.

• Manage Backends modal: src/components/features/backends/manage-backends-modal.tsx lets users edit (host/name/api-key/kind) and remove existing backends, plus add new ones inline via a "+ Add Backend" footer button that opens a BackendFormModal. Both the dropdown footer's "Add backend" and the manage modal's "+ Add Backend" reuse BackendFormModal (see backend-form-modal.tsx), with mode="add" or mode="edit"; AddBackendModal is now a thin compatibility wrapper for BackendFormModal mode="add". The modal is also auto-rendered (with a no-op onClose) by src/root.tsx when the active backend is unreachable, replacing the old full-screen MissingAgentServerNotice onboarding screen.

• Conversation right-panel regression note: ConversationTabs now owns the moved refresh/build buttons, so __tests__/components/features/conversation/conversation-tabs.test.tsx should cover that behavior directly. The drawer's open/closed state (isRightPanelShown / hasRightPanelToggled) is intentionally session-only: it always starts closed on app load (or on opening a fresh/existing conversation after a restart), but it survives in-app navigation because the Zustand useConversationStore stays alive across React Router transitions. The ConversationState localStorage blob (conversation-state-{id}) deliberately does not carry a rightPanelShown field — useConversationLocalStorageState does not expose a setRightPanelShown setter, sanitizeStoredState strips the legacy rightPanelShown key from older persisted blobs on read, and RightPanelToggle / useSelectConversationTab only mutate the in-memory store. In tests, seed the Zustand store directly for selectedTab / isRightPanelShown / hasRightPanelToggled (the component sync effect currently restores only selectedTab from localStorage, so localStorage alone will not make a tab read as active or the drawer read as open).

• Changes tab / FileDiffViewer deleted-file note: the agent-server's /api/git/diff endpoint calls path.exists() first (see openhands-sdk/openhands/sdk/git/git_diff.py → get_git_diff), so requesting a diff for a D (deleted) file returns GitPathError → HTTP 400 and trips the global QueryCache error toast. useUnifiedGitDiff disables the query when type === "D" and FileDiffViewer renders a localized "file deleted" placeholder (DIFF_VIEWER$FILE_DELETED, data-testid="file-deleted-message") instead of the view-mode toolbar / Monaco editor for that case.

• Onboarding modal: src/components/features/onboarding/onboarding-modal.tsx is a 4-step welcome flow rendered by <OnboardingHost /> (mounted on the home route) and gated by the openhands-onboarded localStorage flag (use-onboarding-completion.ts). The four steps live under steps/: choose-agent (Step 0 – OpenHands selectable, Claude Code & Codex disabled with a "coming soon" note), check-backend (embeds the new BackendForm extracted from backend-form-modal.tsx plus a colored connection banner driven by useBackendsHealth), setup-llm (renders <LlmSettingsScreen onSaveSuccess={onNext} /> so the existing settings UI keeps owning validation), and say-hello (text input pre-filled from ONBOARDING$HELLO_DEFAULT_MESSAGE, launches a no-workspace conversation via useCreateConversation and closes the modal). Animation: all four panels are mounted as siblings inside a horizontal rail; advancing/retreating just sets currentStep, which translates the rail by -(step * 100)% for the slide effect. Progress is rendered by OnboardingProgressBar with data-state per segment (completed | current | upcoming). When extending, refactor BackendFormModal carefully — the inner BackendForm is the public surface used both by the modal and by CheckBackendStep; the modal version still owns dirty/save tracking so it keeps "Save"/"Cancel" footer behavior.

• Worktree policy (this conversation): commits are made on the worktree branch and the user expects the worktree to stay attached to that branch. Do NOT run git switch --detach in the worktree and reattach the branch to the main workspace after each commit — only do that when the user explicitly asks. See ~/.openhands/skills/worktree-switch/SKILL.md for the manual procedure the user invokes.

• Files tab diff-view default logic: keyed off useHasAttachedSource() (src/hooks/use-has-attached-source.ts), which is true when the user explicitly attached either a repo (conversation.selected_repository) or a local workspace (getStoredConversationMetadata(id).selected_workspace, persisted by createConversation when workingDirOverride is supplied). The agent-server pre-initialises every conversation workspace as a git worktree for its own change tracking, so do NOT use a filesystem probe (git status / useUnifiedGetGitChanges) as the attachment signal — that was tried in earlier iterations and made every fresh no-attachment conversation incorrectly default to diff view. The companion useHasGitCommits probe (src/hooks/query/use-has-git-commits.ts) then suppresses diff view for attached-but-empty cases (unborn HEAD, non-git workspace).

• Files tab diff-view default logic: keyed off useHasAttachedSource() (src/hooks/use-has-attached-source.ts), which is true when the user explicitly attached either a repo (conversation.selected_repository) or a local workspace (getStoredConversationMetadata(id).selected_workspace, persisted by createConversation when workingDirOverride is supplied). The agent-server pre-initialises every conversation workspace as a git worktree for its own change tracking, so do NOT use a filesystem probe (git status / useUnifiedGetGitChanges) as the attachment signal — that was tried in earlier iterations and made every fresh no-attachment conversation incorrectly default to diff view. The companion useHasGitCommits probe (src/hooks/query/use-has-git-commits.ts) then suppresses diff view for attached-but-empty cases (unborn HEAD, non-git workspace).

• Collapsible thinking: ThinkAction events and LLM extended reasoning (reasoning_content / thinking_blocks on ActionEvent) are rendered as collapsible sections via CollapsibleThinking (src/components/conversation-events/chat/event-message-components/collapsible-thinking.tsx). Collapsed by default to keep the chat compact — the thinking is often in English regardless of the user's conversation language. The getReasoningContent() helper in event-thought-helpers.ts extracts the content, preferring reasoning_content (plain string) and falling back to Anthropic thinking_blocks. i18n keys: THINKING$TITLE, THINKING$EXPAND, THINKING$COLLAPSE. Tests: __tests__/components/conversation-events/chat/event-message-think-action.test.tsx.

• ESLint config (flat, ESLint 9): the project uses eslint.config.js (not .eslintrc) and runs on eslint@9.x, not 10. The constraint pinning us below 10 is eslint-plugin-react@7.37.x, which still calls context.getFilename() at rule-load time — that API was removed in ESLint 10 and @eslint/compat's fixupPluginRules does NOT shim it. Don't try to bump eslint past 9 until eslint-plugin-react ships a v10-compatible release. Import rules come from eslint-plugin-import-x (the maintained fork of eslint-plugin-import) but are registered under both import-x/ and import/ prefixes via plugins: { import: importXPlugin, ... } so existing // eslint-disable-next-line import/... directives keep working. linterOptions.reportUnusedDisableDirectives is set to "warn" (not "off") so stale airbnb-era disable comments still surface in lint output without failing CI. The TS-overrides block has an ignores: ["src/hooks/query/query-keys.ts"] so the no-restricted-syntax rule banning raw ["settings", ...] query keys doesn't fire on the file that defines the helpers themselves. No .npmrc / legacy-peer-deps flag is needed — all our plugins declare ESLint 9 peer compatibility.