github/OpenHands
1
0
Fork 0
mirror of https://github.com/OpenHands/OpenHands.git synced 2026-10-07 16:19:05 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
f4dbfcdf8f78e366c1cff33b9f6aa044d0488b7d
OpenHands/AGENTS.md
T
Rohit Malhotraandopenhands f4dbfcdf8f fix: correct Docker image tag format (remove v prefix) (#339) 
The SDK build script strips the 'v' prefix from semver release tags when
publishing Docker images. The correct tag format is {version}-python
(e.g., 1.22.0-python), not v{version}-python.

This fixes the 'Unable to find image' error when running npm run dev:docker.

Changes:
- Update DEFAULT_AGENT_SERVER_TAG from v1.22.0-python to 1.22.0-python
- Update documentation in AGENTS.md to reflect correct tag format

Co-authored-by: openhands <openhands@all-hands.dev>
2026-05-11 16:27:49 -04:00

44 KiB
Raw Blame History

Repository Notes

  • 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 from agent_server LLM endpoints.
    • settings-service uses agent server /api/settings endpoints 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 are mapped directly to agent_server REST endpoints.
    • open-hands-axios injects the optional X-Session-API-Key from env/local config for all requests.

  • 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.

  • 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 consumed directly from github:OpenHands/typescript-client#6b9603f; that package ships the needed 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.

  • Shared TypeScript-client adapters live in src/api/typescript-client.ts; prefer those helpers for agent-server-backed REST/workspace/event/VS Code calls before falling back to open-hands-axios.

  • 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 uv, optional .env, run npm run dev).

  • 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.0")
    • 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.0 for agent-server SDK libraries

  • scripts/dev-docker.mjs runs the agent-server inside a Docker container instead of via uvx. The default image uses versioned release tags:

    • DEFAULT_AGENT_SERVER_TAG — uses format {version}-python (e.g., 1.22.0-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

  • Security: Both scripts/dev-safe.mjs and scripts/dev-with-automation.mjs auto-generate random API keys on each startup for better security isolation:

    • SESSION_API_KEY — 64-character hex (256-bit) for agent-server API authentication; auto-generated per session unless overridden via env var
    • AUTOMATION_LOCAL_API_KEY — 64-character hex for automation backend auth; auto-generated per session 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 full stack with automation by default (via dev:automation). Use npm run dev:minimal for agent-server + Vite only.

  • scripts/dev-with-automation.mjs runs the full stack: agent-server, automation backend (both via uvx), Vite dev server, and ingress proxy. Uses a standalone ingress proxy (scripts/ingress.mjs) to route traffic:

    • /api/automation/* → automation backend (:18001)
    • /api/*, /sockets, etc. → agent server (:18000)
    • /* (default) → Vite dev server (:3001)
    • 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: auto-generated random key per session)
    • Access points: http://localhost:8000/ (main UI), http://localhost:8000/api/automation/docs (API docs)
    • Security: AUTOMATION_LOCAL_API_KEY is auto-generated using crypto.randomBytes(32) on each startup for better security isolation. Set the env var explicitly to use a consistent key across restarts. 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/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.

  • 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. 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. In those tests, seed both the persisted conversation-state key and the Zustand store (selectedTab, isRightPanelShown, hasRightPanelToggled) — the component sync effect currently restores hasRightPanelToggled from localStorage, not isRightPanelShown, so localStorage alone will not make a tab read as active.

  • 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.

Reference in New Issue View Git Blame Copy Permalink