Add files using upload-large-folder tool

.dockerignore

@@ -0,0 +1,39 @@
+# Dependencies
+node_modules/
+
+# Build outputs (rebuilt in Docker)
+build/
+dist/
+
+# Development files
+.git/
+.github/
+.openhands/
+.agents/
+.pr/
+
+# Test files
+__tests__/
+tests/
+__mocks__/
+test-results/
+playwright-report*/
+coverage/
+
+# IDE / OS
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.*
+!.env.sample
+
+# Misc
+artifacts/
+*.tgz
+*.log

.env.sample

@@ -0,0 +1,37 @@
+# OpenHands Agent Server target
+# These defaults assume you are manually pointing the frontend at a backend on
+# 127.0.0.1:8000. The recommended local workflow is `npm run dev`, which starts
+# an isolated local backend for this checkout. Use `npm run dev:frontend` only
+# when you intentionally want to point at a separately managed backend.
+VITE_BACKEND_HOST="127.0.0.1:8000" # Host:port used by the Vite dev proxy
+VITE_BACKEND_BASE_URL="http://127.0.0.1:8000" # Base URL used by browser-side direct requests
+# To drive a containerized ACP agent-server, point this at the published port,
+# e.g. VITE_BACKEND_BASE_URL="http://localhost:8010" — see examples/acp-docker/
+# and docs/ACP_AGENTS.md → "Running ACP agents in a Docker container".
+# VITE_SESSION_API_KEY="" # Set to the same value as backend SESSION_API_KEY or OH_SESSION_API_KEYS_0 when auth is enabled
+# VITE_WORKING_DIR="/workspace/project/agent-canvas" # Base dir for per-conversation working_dirs. Each conversation's working_dir is <VITE_WORKING_DIR>/<id_hex>. Defaults to <OH_CANVAS_SAFE_STATE_DIR>/workspaces, which is the sibling of the agent server's <state_dir>/conversations/ persistence dir — both share the same <id_hex> per conversation.
+# VITE_ENABLE_BROWSER_TOOLS="true" # Set to false to omit BrowserToolSet from new conversations
+
+# Frontend dev server
+VITE_FRONTEND_PORT="3001" # Port to run the frontend application
+VITE_USE_TLS="false" # Use HTTPS/WSS for proxied backend connections
+VITE_INSECURE_SKIP_VERIFY="false" # Skip TLS certificate verification for proxied backend requests
+# VITE_BASE_PATH="/canvas" # Build/serve the SPA under a subpath. Leave unset for root-local development.
+
+# Public PostHog client key compiled into source builds. Precompiled library
+# consumers can instead pass apiKey/apiHost/uiHost to AgentServerUIProviders.
+# VITE_POSTHOG_API_KEY="phc_..."
+# VITE_DO_NOT_TRACK="1" # Disable all telemetry, including anonymous install counts
+
+# Mocking / test helpers
+VITE_MOCK_API="false" # Enable/disable API mocking with MSW
+
+# `npm run dev` (scripts/dev-safe.mjs) — isolated local backend via uvx
+# OH_CANVAS_SAFE_BACKEND_PORT="18000" # Port the spawned agent-server listens on
+# OH_CANVAS_SAFE_VSCODE_PORT="18001" # Port forwarded to the embedded VS Code (defaults to backend port + 1)
+# OH_CANVAS_SAFE_STATE_DIR="$HOME/.openhands/agent-canvas" # Where conversations and bash events are stored (tmux sockets live under /tmp)
+
+# Agent server version selection (uvx) — listed in order of precedence (highest first)
+# OH_AGENT_SERVER_LOCAL_PATH="" # Absolute path to a local software-agent-sdk checkout. Runs the local checkout via uvx with editable openhands-sdk/tools/workspace installs so source edits are picked up on restart. Highest precedence.
+# OH_AGENT_SERVER_GIT_REF="" # Git commit SHA or branch name (e.g., "main", "abc1234"). Takes precedence over version.
+# OH_AGENT_SERVER_VERSION="" # Specific PyPI version (e.g., "1.18.0"). Uses latest release if unset.

.gitattributes

@@ -1,35 +1,6 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+* text=auto eol=lf
+
+# Icon binaries — never text-normalize (a mangled byte corrupts the file).
+*.png binary
+*.ico binary
+*.icns binary

.gitignore

@@ -0,0 +1,45 @@
+# i18n translation files make by script using `make build`
+public/locales/**/*
+src/i18n/declaration.ts
+.env
+.envrc
+node_modules/
+build/
+logs/
+/.tmp/live-e2e-state/
+# Scratch space for local E2E runs. Ignore the whole directory: besides the
+# mock-llm state dirs, the suite also drops an automation DB and an unignored
+# `secrets.json` here, which should never be committable.
+/.tmp/
+dist/
+__pycache__
+
+
+/test-results/
+/test-results-live/
+/test-results-mock-llm/
+/test-results-mock-llm-docker/
+/.mock-llm-markers/
+/playwright-report/
+/playwright-report-live/
+/playwright-report-mock-llm/
+/playwright-report-mock-llm-docker/
+/blob-report/
+/playwright/.cache/
+/.stryker-tmp/
+/reports/
+.react-router/
+ralph/
+.vercel
+*.tgz
+
+# Local runtime artifacts produced by static-server / agent-server runs
+workspace/
+build-fresh/
+
+# Electron desktop build outputs
+/dist-electron/
+# Downloaded uv binary (populated by `npm run download-uv` before packaging)
+/resources/bin/
+# Downloaded Node.js distribution (populated by `npm run download-node` before packaging)
+/resources/node/

.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged

.npmignore

@@ -0,0 +1,51 @@
+# npm ignore file - overrides .gitignore for npm publish
+# We need to INCLUDE build/ and dist/ which are in .gitignore
+
+# Source files (not needed in package)
+src/
+__tests__/
+tests/
+*.test.ts
+*.test.tsx
+*.spec.ts
+
+# Development config
+.github/
+.husky/
+.openhands/
+.agents/
+.vscode/
+*.config.ts
+*.config.js
+*.config.mjs
+tsconfig*.json
+eslint.config.mjs
+.eslintrc*
+.prettierrc*
+vitest.setup.ts
+
+# Development docs
+DEVELOPMENT.md
+AGENTS.md
+CHANGELOG.md
+
+# Generated files we don't need
+public/locales/
+src/i18n/declaration.ts
+.env*
+.envrc
+
+# Test artifacts
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/
+coverage/
+
+# Misc
+node_modules/
+*.tgz
+.react-router/
+.vercel
+ralph/
+artifacts/

.openhands/setup.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+ENV_FILE="$REPO_ROOT/.env"
+
+cd "$REPO_ROOT" || exit 1
+
+# Install uv if not present (required for running agent-server via uvx)
+if ! command -v uvx &> /dev/null; then
+  echo "Installing uv..."
+  curl -LsSf https://astral.sh/uv/install.sh | sh
+
+  # Add uv to PATH for the rest of this script
+  export PATH="$HOME/.local/bin:$PATH"
+
+  # Verify installation
+  if ! command -v uvx &> /dev/null; then
+    echo "Warning: uv installed but uvx not found in PATH."
+    echo "You may need to add ~/.local/bin to your PATH:"
+    echo '  export PATH="$HOME/.local/bin:$PATH"'
+  fi
+fi
+
+# Always run npm ci to ensure dependencies are installed and up-to-date.
+# This is idempotent and ensures hooks (like on_stop.sh) have access to
+# npm scripts like lint and test.
+npm ci
+
+if [ ! -f "$ENV_FILE" ]; then
+  cp .env.sample "$ENV_FILE"
+fi
+
+if ! grep -Eq '^[[:space:]]*VITE_WORKING_DIR=' "$ENV_FILE"; then
+  printf '\nVITE_WORKING_DIR="%s"\n' "$REPO_ROOT" >> "$ENV_FILE"
+fi
+
+if [ ! -f src/i18n/declaration.ts ]; then
+  npm run make-i18n
+fi

.prettierrc.json

@@ -0,0 +1,3 @@
+{
+    "trailingComma": "all"
+}

.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "1.18.0"
+}

CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0-alpha.2] - 2025-05-11
+
+### Added
+
+- Initial npm package release of `@openhands/agent-canvas`
+- CLI entry point (`npx @openhands/agent-canvas`) to run full stack locally
+- Library build mode with component barrel exports
+- Subpath exports for modular imports:
+  - `@openhands/agent-canvas/browser`
+  - `@openhands/agent-canvas/conversation`
+  - `@openhands/agent-canvas/files`
+  - `@openhands/agent-canvas/settings`
+  - `@openhands/agent-canvas/sidebar`
+  - `@openhands/agent-canvas/terminal`
+  - `@openhands/agent-canvas/i18n`
+- TypeScript type declarations
+- GitHub Actions workflow for automated npm publishing (OIDC trusted publishing)
+
+[Unreleased]: https://github.com/OpenHands/agent-canvas/compare/v1.0.0-alpha.2...HEAD
+[1.0.0-alpha.2]: https://github.com/OpenHands/agent-canvas/releases/tag/v1.0.0-alpha.2

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright © 2025 OpenHands contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,170 @@
+---
+license: mit
+tags:
+  - agent
+  - coding-agent
+  - cli
+  - llm
+  - tool-use
+---
+
+<a name="readme-top"></a>
+
+> **This is a source mirror.** This Hugging Face repository is not a model checkpoint — it's a read-only mirror of the [`OpenHands/OpenHands`](https://github.com/OpenHands/OpenHands) GitHub repository, the OpenHands AI-driven development platform (source of the official `openhands` pip package). It is hosted here for visibility on the Hub; the canonical repository, issue tracker, and pull requests all live on GitHub. Please file issues and contribute there, not here.
+
+<div align="center">
+  <img src="https://assets.openhands.dev/logo-whitebackground.png" alt="OpenHands logo" width="340">
+  <h1 align="center" style="border-bottom: none">Agent Canvas</h1>
+  <p align="center">
+    <strong>The self-hosted developer control center for coding agents and automations.</strong>
+  </p>
+  <p align="center">
+    Run OpenHands, Claude Code, Codex, Gemini, or any ACP-compatible agent across local, remote, and cloud backends.
+  </p>
+</div>
+<div align="center">
+  <a href="https://github.com/OpenHands/incubator-program"><img src="https://img.shields.io/badge/status-beta-blue?style=for-the-badge" alt="Project status beta"></a>
+  <a href="https://github.com/OpenHands/OpenHands/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/OpenHands/OpenHands/ci.yml?branch=main&style=for-the-badge" alt="CI status"></a>
+  <a href="https://www.npmjs.com/package/@openhands/agent-canvas"><img src="https://img.shields.io/npm/v/%40openhands%2Fagent-canvas?style=for-the-badge&logo=npm" alt="npm version"></a>
+  <a href="https://docs.openhands.dev/openhands/usage/agent-canvas/backends"><img src="https://img.shields.io/badge/Documentation-000?logo=googledocs&logoColor=FFE165&style=for-the-badge" alt="Documentation"></a>
+  <a href="https://go.openhands.dev/slack"><img src="https://img.shields.io/badge/Slack-Join%20the%20community-611f69?logo=slack&logoColor=white&style=for-the-badge" alt="Join us on Slack"></a>
+</div>
+<div align="center">
+  <a href="#quickstart">Quickstart</a> |
+  <a href="./docs/README.md">Docs</a> |
+  <a href="./docs/SELF_HOSTING.md">Self-Hosting</a> |
+  <a href="https://docs.openhands.dev/openhands/usage/agent-canvas/acp-agents">ACP Agents</a> |
+  <a href="https://docs.openhands.dev/openhands/usage/agent-canvas/prebuilt-automations">Automations</a> |
+  <a href="https://go.openhands.dev/slack">Slack</a>
+</div>
+<p align="center">
+  <img src="https://assets.openhands.dev/screenshot/automation-preview.png" alt="Agent Canvas automation preview" width="100%">
+</p>
+<hr>
+
+OpenHands Agent Canvas turns your coding agents into a self-hosted, always-on engineering team. It's a developer control center for starting conversations and automating everyday tasks — like generating reports that publish to Slack or automatically decomposing GitHub issues into tasks.
+
+It runs locally on your machine by default, but can connect to multiple “agent backends”, e.g. running agents in Docker containers, on VMs, or within your company infrastructure. You can optionally choose to run agents on OpenHands Cloud or OpenHands Enterprise infrastructure.
+
+Agent Canvas runs the open source OpenHands agent out-of-the-box, but can use any third-party agent like Claude Code and Codex.
+
+|                                                                                                                      |                                                                                                                                          |
+| -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| [**Self-host your way**](https://docs.openhands.dev/openhands/usage/agent-canvas/backend-setup/vm)                   | Run agents locally, in Docker, on VMs, or anywhere you can run an agent server backend                                                   |
+| [**Switch between different backends**](https://docs.openhands.dev/openhands/usage/agent-canvas/backends)            | Switch between local, remote, and cloud agents without losing focus                                                                      |
+| [**Create automations**](https://docs.openhands.dev/openhands/usage/agent-canvas/prebuilt-automations)               | Create automations and workflows that integrate with Slack, GitHub, Linear, and more. Run on a schedule or in response to webhook events |
+| [**Integrate with the tools you use**](https://docs.openhands.dev/openhands/usage/agent-canvas/prebuilt-automations) | Connect your automations with third-party services like Slack, GitHub, Notion, and more to automate workflows                            |
+| [**Bring your own model**](https://docs.openhands.dev/openhands/usage/settings/llm-settings#llm-profiles)            | Use with any LLM                                                                                                                         |
+| [**Use with any agent**](https://docs.openhands.dev/openhands/usage/agent-canvas/acp-agents)                         | Use with OpenHands, Claude Code, Codex, Gemini, or any agent with Agent-Client Protocol (ACP).                                           |
+
+If you have questions or feedback, please open a GitHub issue or join the [#proj-agent-canvas channel in Slack](https://openhands.dev/joinslack).
+
+## Quickstart
+
+You can install OpenHands to run agents on any machine: on your laptop, on a dedicated computer like a Mac Mini,
+or on a server in the cloud.
+
+The most powerful way to run OpenHands is on a server in the cloud. This allows your agents to continue running
+even when your laptop is shut, and makes it easier to trigger your agents through third-party services
+like Slack, GitHub, and Datadog. See [SELF_HOSTING.md](docs/SELF_HOSTING.md) for details, especially with respect to security hardening.
+
+Notably, you can run the backend in _multiple different environments_, and switch between
+them from the same Agent Canvas frontend. E.g. you can share an Agent Server with your team for agents doing
+code review and dependency updates, then have your personal agents running on your laptop.
+
+### Option 1: Without a Sandbox
+
+> [!WARNING]
+> This runs the agent-server directly on the machine you're installing on — the agent will have full access to your filesystem!
+
+**Prerequisites**: Node.js 22.12.x or later, `uv`
+
+```sh
+npm install -g @openhands/agent-canvas
+agent-canvas
+```
+
+The `agent-canvas` command starts the full local stack by default. You can also split it when you want to run pieces separately:
+
+```sh
+agent-canvas --frontend-only  # static frontend + ingress only
+agent-canvas --backend-only   # agent server + automation backend + ingress only
+```
+
+### Option 2: With a Docker Sandbox
+
+**Prerequisites**:
+
+- Docker: Docker Desktop on macOS/Windows, or Docker Engine/Docker Desktop on Linux.
+- A host directory for `PROJECTS_PATH` containing the project folders you want the agent to access. Create it before starting the container.
+
+**macOS / Linux:**
+
+```sh
+export PROJECTS_PATH="$HOME/projects"  # directory containing your project folders
+mkdir -p "$PROJECTS_PATH" "$HOME/.openhands"
+
+docker run -it --rm \
+  -p 8000:8000 \
+  -v "$HOME/.openhands:/home/openhands/.openhands" \
+  -v "${PROJECTS_PATH}:/projects" \
+  ghcr.io/openhands/agent-canvas:1.18.0 # x-release-please-version
+```
+
+**Windows (PowerShell / Windows Terminal):** See [README.windows.md](./README.windows.md) for the equivalent commands.
+
+The agent will be able to access any project under `PROJECTS_PATH`.
+
+### Option 3: From Source
+
+> [!WARNING]
+> This runs the agent-server directly on the machine you're installing on — the agent will have full access to your filesystem!
+
+**Prerequisites**: Node.js 22.12.x or later, `npm`, `uv` (for running the agent server via `uvx`)
+
+```sh
+git clone https://github.com/OpenHands/OpenHands.git
+cd OpenHands
+npm install
+npm run dev
+```
+
+---
+
+Access the UI at [http://localhost:8000](http://localhost:8000) for the npm/source launchers, or [http://localhost:8000/canvas](http://localhost:8000/canvas) for the Docker image. You can add additional backends directly from the UI.
+
+# Architecture
+
+Agent Canvas is powered by the [OpenHands Agent Server](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-agent-server/openhands/agent_server), a REST API for running multiple agents on a single machine. Each Agent Server runs on a single host/port; the Agent Canvas can connect to multiple Agent Servers and easily flip between them.
+
+You can run an Agent Server anywhere:
+
+- Directly on your laptop (be careful!)
+- On a dedicated machine like a Mac Mini
+- On a virtual machine in the cloud
+- Inside OpenHands Cloud (our commercial offering)
+
+The Agent Server is often paired with an [Automation Server](https://github.com/OpenHands/automation), which lets you set up agents that run on a schedule or in response to events.
+
+<img width="1456" height="1258" alt="image" src="https://github.com/user-attachments/assets/cb6de6f5-ac30-4d04-a76a-b5c259f0c163" />
+
+### Repository boundaries
+
+Agent Canvas is part of a multi-repository OpenHands system. Changes should go to the repository that owns the behavior:
+
+| Repository | Responsibility |
+|---|---|
+| [`OpenHands/OpenHands`](https://github.com/OpenHands/OpenHands) | Agent Canvas frontend, user-facing control center, backend selection, and local-stack orchestration. |
+| [`OpenHands/software-agent-sdk`](https://github.com/OpenHands/software-agent-sdk) | Python SDK, Agent Server, agents, tools, conversations, workspaces, events, and the canonical server API. |
+| [`OpenHands/typescript-client`](https://github.com/OpenHands/typescript-client) | Browser-compatible TypeScript client for the Agent Server API. |
+| [`OpenHands/automation`](https://github.com/OpenHands/automation) | Automation definitions, scheduling, webhooks, run history, and dispatching. |
+
+The Agent Server API is implemented by the SDK and consumed through the TypeScript client by Agent Canvas. The automation service decides when work runs and dispatches conversations to the Agent Server/SDK, which decides what runs. See [`AGENTS.md`](./AGENTS.md) for contributor-specific boundaries and the required custom code-review guide.
+
+
+## More documentation
+
+- [Documentation index](./docs/README.md)
+- [Architecture overview](./docs/architecture.md)
+- [Development guide](./docs/DEVELOPMENT.md)
+- [Self-hosting guide](./docs/SELF_HOSTING.md)

README.windows.md

@@ -0,0 +1,29 @@
+# Windows quickstart (PowerShell)
+
+This doc contains **Windows-specific** command syntax for running Agent Canvas with the **Docker sandbox**.
+
+For the main install options and overall context, see [README.md](./README.md).
+
+## Option 2: With a Docker Sandbox (Windows)
+
+**Prerequisites**:
+
+- Docker Desktop for Windows
+- A host directory for `PROJECTS_PATH` containing the project folders you want the agent to access (create it before starting the container)
+
+```powershell
+docker pull ghcr.io/openhands/agent-canvas:1.18.0 # x-release-please-version
+
+$env:PROJECTS_PATH = Join-Path $HOME "projects"  # directory containing your project folders
+New-Item -ItemType Directory -Force -Path $env:PROJECTS_PATH, (Join-Path $env:USERPROFILE ".openhands") | Out-Null
+
+docker run -it --rm `
+  -p 8000:8000 `
+  -v "$($env:USERPROFILE)\.openhands:/home/openhands/.openhands" `
+  -v "$($env:PROJECTS_PATH):/projects" `
+  ghcr.io/openhands/agent-canvas:1.18.0 # x-release-please-version
+```
+
+Open [http://localhost:8000/canvas](http://localhost:8000/canvas) in your browser.
+
+The agent will be able to access any project under `PROJECTS_PATH`.

__mocks__/zustand.ts

@@ -0,0 +1,60 @@
+import { act } from "@testing-library/react";
+import { vi, afterEach } from "vitest";
+import type * as ZustandExportedTypes from "zustand";
+
+export * from "zustand";
+
+const { create: actualCreate, createStore: actualCreateStore } =
+  await vi.importActual<typeof ZustandExportedTypes>("zustand");
+
+// a variable to hold reset functions for all stores declared in the app
+export const storeResetFns = new Set<() => void>();
+
+const createUncurried = <T>(
+  stateCreator: ZustandExportedTypes.StateCreator<T>,
+) => {
+  const store = actualCreate(stateCreator);
+  const initialState = store.getInitialState();
+  storeResetFns.add(() => {
+    store.setState(initialState, true);
+  });
+  return store;
+};
+
+// when creating a store, we get its initial state, create a reset function and add it in the set
+export const create = (<T>(
+  stateCreator: ZustandExportedTypes.StateCreator<T>,
+) =>
+  // to support curried version of create
+  typeof stateCreator === "function"
+    ? createUncurried(stateCreator)
+    : createUncurried) as typeof ZustandExportedTypes.create;
+
+const createStoreUncurried = <T>(
+  stateCreator: ZustandExportedTypes.StateCreator<T>,
+) => {
+  const store = actualCreateStore(stateCreator);
+  const initialState = store.getInitialState();
+  storeResetFns.add(() => {
+    store.setState(initialState, true);
+  });
+  return store;
+};
+
+// when creating a store, we get its initial state, create a reset function and add it in the set
+export const createStore = (<T>(
+  stateCreator: ZustandExportedTypes.StateCreator<T>,
+) =>
+  // to support curried version of createStore
+  typeof stateCreator === "function"
+    ? createStoreUncurried(stateCreator)
+    : createStoreUncurried) as typeof ZustandExportedTypes.createStore;
+
+// reset all stores after each test run
+afterEach(() => {
+  act(() => {
+    storeResetFns.forEach((resetFn) => {
+      resetFn();
+    });
+  });
+});

bin/agent-canvas.mjs

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for @openhands/agent-canvas
+ *
+ * Runs the full Agent Canvas stack locally by default:
+ * - Agent-server via uvx
+ * - Automation backend via uvx
+ * - Pre-built static frontend
+ *
+ * This is the production equivalent of `npm run dev` - it runs the full stack
+ * but serves pre-built static assets instead of the Vite dev server.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_JSON = join(__dirname, "..", "package.json");
+// Build output is in build/ (not build/client/) - see react-router.config.ts unpackClientDirectory
+const BUILD_DIR = join(__dirname, "..", "build");
+
+const DEFAULTS_JSON = join(__dirname, "..", "config", "defaults.json");
+
+// Check for version/help/info/public flags first
+const args = process.argv.slice(2);
+if (args.includes("-v") || args.includes("--version")) {
+  const { version } = JSON.parse(readFileSync(PKG_JSON, "utf-8"));
+  console.log(version);
+  process.exit(0);
+}
+if (args.includes("--info")) {
+  const { version } = JSON.parse(readFileSync(PKG_JSON, "utf-8"));
+  const defaults = JSON.parse(readFileSync(DEFAULTS_JSON, "utf-8"));
+  console.log(`@openhands/agent-canvas ${version}
+
+Default stack versions:
+  agent-server:    ${defaults.versions.agentServer}
+  automation:      ${defaults.versions.automation}
+
+Compatibility:
+  agent-server:    >= ${defaults.compatibility.minimumAgentServer}
+
+Default ports:
+  ingress:         ${defaults.ports.proxy}
+  agent-server:    ${defaults.ports.agentServer}
+  automation:      ${defaults.ports.automation}
+
+Override versions via environment variables:
+  OH_AGENT_SERVER_VERSION, OH_AGENT_SERVER_GIT_REF, OH_AGENT_SERVER_LOCAL_PATH
+  OH_AUTOMATION_VERSION, OH_AUTOMATION_GIT_REF`);
+  process.exit(0);
+}
+const isPublic = args.includes("--public");
+const isFrontendOnly = args.includes("--frontend-only");
+const isBackendOnly = args.includes("--backend-only");
+
+if (args.includes("-h") || args.includes("--help")) {
+  console.log(`
+@openhands/agent-canvas - Run the Agent Canvas UI with agent-server
+
+Runs the full stack with agent-server and automation backend via uvx,
+and serves pre-built static frontend assets.
+
+USAGE:
+  npx @openhands/agent-canvas [options]
+
+AUTH MODES:
+  By default the server auto-generates an API key that is injected into
+  the frontend at startup — no login required.
+
+  --public    Enable public mode. Requires LOCAL_BACKEND_API_KEY env var.
+              The key protects the server but is NOT injected into the
+              frontend. Users must paste it when the UI loads.
+
+OPTIONS:
+  -p, --port <port>     Ingress port (default: 8000)
+  --public              Enable public mode (see above)
+  --frontend-only       Start only the static frontend behind ingress
+  --backend-only        Start only agent-server + automation behind ingress
+  -v, --version         Show version number
+  --info                Show version and default stack configuration
+  -h, --help            Show this help message
+
+ENVIRONMENT VARIABLES:
+  LOCAL_BACKEND_API_KEY        API key for the server. Required in --public
+                               mode; optional otherwise (auto-generated if
+                               omitted, persisted across restarts).
+  OH_SECRET_KEY                Secret key for encrypting settings
+  OH_AGENT_SERVER_GIT_REF      Git ref for agent-server
+  OH_AGENT_SERVER_LOCAL_PATH   Path to local SDK checkout (for development)
+  OH_AGENT_SERVER_VERSION      Specific PyPI version for agent-server
+
+Note: LLM settings are configured through the web UI settings page,
+not environment variables.
+
+EXAMPLES:
+  # Start full stack (local mode, auto-generated key)
+  npx @openhands/agent-canvas
+
+  # Pin a specific key (local mode, key auto-injected into frontend)
+  LOCAL_BACKEND_API_KEY=my-key npx @openhands/agent-canvas
+
+  # Public mode — users must enter the API key in the browser
+  LOCAL_BACKEND_API_KEY=my-secret npx @openhands/agent-canvas --public
+
+  # Use a specific port
+  npx @openhands/agent-canvas --port 3000
+
+  # Start only the static frontend behind ingress
+  npx @openhands/agent-canvas --frontend-only
+
+  # Start only the agent-server and automation backend behind ingress
+  npx @openhands/agent-canvas --backend-only
+
+  # Show default stack versions and ports
+  npx @openhands/agent-canvas --info
+
+  # Use local SDK checkout for development
+  OH_AGENT_SERVER_LOCAL_PATH=/path/to/sdk npx @openhands/agent-canvas
+`);
+  process.exit(0);
+}
+
+if (isFrontendOnly && isBackendOnly) {
+  console.error(
+    "Error: --frontend-only and --backend-only cannot be used together",
+  );
+  process.exit(1);
+}
+
+if (isFrontendOnly && isPublic) {
+  console.error("Error: --public cannot be used with --frontend-only");
+  process.exit(1);
+}
+
+// Check build exists before doing anything else unless no frontend will run.
+if (!isBackendOnly && !existsSync(BUILD_DIR)) {
+  console.error(`
+Error: No build found at ${BUILD_DIR}
+
+This package needs to be built first. If you installed from npm,
+this is a packaging error. If running from source:
+
+  npm install
+  npm run build
+`);
+  process.exit(1);
+}
+
+let main;
+try {
+  ({ main } = await import("../scripts/dev-with-automation.mjs"));
+} catch (err) {
+  console.error("Failed to load required scripts. Try reinstalling:");
+  console.error("  npm install -g @openhands/agent-canvas@latest");
+  console.error(`\nError: ${err.message}`);
+  process.exit(1);
+}
+
+main({
+  bannerTitle: "Agent Canvas",
+  staticMode: true,
+  staticDir: BUILD_DIR,
+  mode: "agent-canvas",
+  isPublic,
+}).catch((err) => {
+  console.error(`Fatal error: ${err.message}`);
+  if (err.stack) {
+    console.error(err.stack);
+  }
+  process.exit(1);
+});

config/defaults.json

@@ -0,0 +1,45 @@
+{
+  "_comment": "Single source of truth for version pins, ports, paths, and defaults shared across the npm and Docker install paths. Read by scripts/dev-safe.mjs, scripts/dev-with-automation.mjs, docker/entrypoint.sh (via generated defaults.env), and .github/workflows/docker.yml.",
+  "versions": {
+    "agentServer": "1.46.0",
+    "agentCanvas": "1.18.0",
+    "automation": "1.11.1"
+  },
+  "compatibility": {
+    "minimumAgentServer": "1.28.0"
+  },
+  "constraints": {
+    "_comment": "Temporary upper bound on the agent-client-protocol (acp) transitive dependency. openhands-sdk 1.35.0 requires agent-client-protocol>=0.10.1 with no upper bound, but acp 0.11.0 reordered the ACP prompt() arguments and breaks the SDK's ACP client (a PromptRequest validation error surfaces as 'ACP error: 2 validation errors for PromptRequest'). Pin acp <0.11 until a fixed openhands-sdk ships. Consumed by scripts/dev-safe.mjs (agent-server uvx install) and .github/workflows/mock-llm-e2e.yml (mock ACP server venv).",
+    "agentClientProtocol": "agent-client-protocol<0.11"
+  },
+  "images": {
+    "agentServer": "ghcr.io/openhands/agent-server",
+    "agentCanvas": "ghcr.io/openhands/agent-canvas"
+  },
+  "ports": {
+    "agentServer": 18000,
+    "automation": 18001,
+    "proxy": 8000,
+    "_vscodeComment": "Port the bundled editor binds to inside the container; agent-server's own default. Only the Docker entrypoint reads this — the npm launchers derive the editor port from the agent-server port so several stacks can run side by side. It is never published: the editor is reached through paths.vscodeBasePath on the proxy port.",
+    "vscode": 8001
+  },
+  "paths": {
+    "stateSubdir": "agent-canvas",
+    "conversations": "agent-canvas/conversations",
+    "bashEvents": "agent-canvas/bash_events",
+    "automationDb": "automation/automations.db",
+    "canvasBasePath": "/canvas",
+    "_vscodeBasePathComment": "Path prefix the bundled editor is served under, on the same origin as the canvas. Passed to agent-server as OH_VSCODE_BASE_PATH (it launches openvscode-server with --server-base-path and advertises the prefix in /api/vscode/url), and registered as an ingress route to the VSCode port. Keeping one value on both sides is what lets a single-origin deployment reach the editor without publishing a second port. Tradeoff: a path prefix routes but does not isolate, so the editor shares the canvas's browser origin and therefore its localStorage — see docs/SELF_HOSTING.md and OpenHands/OpenHands#16492.",
+    "vscodeBasePath": "/vscode"
+  },
+  "packages": {
+    "agentServer": "openhands-agent-server",
+    "automation": "openhands-automation",
+    "tools": "openhands-tools",
+    "workspace": "openhands-workspace"
+  },
+  "telemetry": {
+    "posthogApiKey": "phc_kBtz5nKmxVRRQ7HtPwr2QX9eMC5j65zE86QKocVNwb4U",
+    "posthogHost": "https://us.i.posthog.com"
+  }
+}

docker/Dockerfile

@@ -0,0 +1,170 @@
+# syntax=docker/dockerfile:1.7
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# agent-canvas all-in-one Docker image
+#
+# Combines three services into a single image:
+#   1. Agent Server  — from ghcr.io/openhands/agent-server (upstream SDK image)
+#   2. Automation    — installed via pip from openhands-automation
+#   3. Frontend      — agent-canvas static build served by Node.js
+#
+# The entrypoint starts all three services and an ingress proxy that unifies
+# them behind a single port (default 8000):
+#   /api/automation/*  → automation backend (:18001)
+#   /api/*, /sockets   → agent server (:18000)
+#   /* (default)       → static frontend + SPA fallback
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# ── Build args ────────────────────────────────────────────────────────────────
+# No hardcoded defaults — values are derived from config/defaults.json.
+# CI passes these via --build-arg; for local builds use:
+#   node scripts/docker-build.mjs          (recommended, reads JSON for you)
+#   docker build --build-arg AGENT_SERVER_IMAGE=... --build-arg AUTOMATION_VERSION=... -f docker/Dockerfile .
+ARG AGENT_SERVER_IMAGE
+ARG AUTOMATION_VERSION
+
+# ── Stage 1: Build frontend ──────────────────────────────────────────────────
+FROM node:24-slim AS frontend-build
+
+WORKDIR /build
+
+# Cache-friendly: package files first
+COPY package.json package-lock.json ./
+RUN npm ci
+
+# Copy everything needed for the build
+COPY . .
+
+# Build the static frontend.
+# VITE_POSTHOG_API_KEY is a public client key baked into the bundle. CI passes
+# production for tagged releases and staging for PR/main images.
+# VITE_BASE_PATH is baked into React Router/Vite so the Docker image serves
+# Canvas under the Cloud subpath instead of a dedicated hostname.
+ARG VITE_POSTHOG_API_KEY=""
+ARG VITE_BASE_PATH="/canvas"
+ENV VITE_POSTHOG_API_KEY=${VITE_POSTHOG_API_KEY}
+ENV VITE_BASE_PATH=${VITE_BASE_PATH}
+RUN npm run build
+
+# ── Stage 1b: Generate shell-sourceable defaults from config/defaults.json ──
+# This avoids needing jq/python at container runtime to parse the JSON.
+FROM node:24-slim AS config-gen
+COPY config/defaults.json /tmp/
+RUN node -e " \
+  const c = JSON.parse(require('fs').readFileSync('/tmp/defaults.json','utf-8')); \
+  const lines = [ \
+    'CONFIG_AGENT_SERVER_PORT=' + c.ports.agentServer, \
+    'CONFIG_AUTOMATION_PORT=' + c.ports.automation, \
+    'CONFIG_PROXY_PORT=' + c.ports.proxy, \
+    'CONFIG_VSCODE_PORT=' + c.ports.vscode, \
+    'CONFIG_STATE_SUBDIR=' + c.paths.stateSubdir, \
+    'CONFIG_CONVERSATIONS=' + c.paths.conversations, \
+    'CONFIG_BASH_EVENTS=' + c.paths.bashEvents, \
+    'CONFIG_AUTOMATION_DB=' + c.paths.automationDb, \
+    'CONFIG_CANVAS_BASE_PATH=' + c.paths.canvasBasePath, \
+    'CONFIG_VSCODE_BASE_PATH=' + c.paths.vscodeBasePath, \
+    'CONFIG_POSTHOG_API_KEY=' + c.telemetry.posthogApiKey, \
+    'CONFIG_POSTHOG_HOST=' + c.telemetry.posthogHost, \
+  ]; \
+  require('fs').writeFileSync('/tmp/defaults.env', lines.join('\n') + '\n'); \
+"
+
+# ── Stage 2: Combined image ──────────────────────────────────────────────────
+FROM ${AGENT_SERVER_IMAGE} AS final
+
+ARG AUTOMATION_VERSION
+ARG AGENT_SERVER_SDK_GIT_REF=""
+ARG OPENHANDS_BUILD_GIT_SHA=unknown
+ARG OPENHANDS_BUILD_GIT_REF=unknown
+ARG VITE_BASE_PATH="/canvas"
+ARG VITE_POSTHOG_API_KEY=""
+
+ARG AGENT_CANVAS_VERSION=dev
+LABEL org.opencontainers.image.title="agent-canvas"
+LABEL org.opencontainers.image.description="All-in-one agent-canvas: Agent Server + Automation + Frontend"
+LABEL org.opencontainers.image.source="https://github.com/OpenHands/OpenHands"
+LABEL org.opencontainers.image.version="${AGENT_CANVAS_VERSION}"
+LABEL org.opencontainers.image.revision="${OPENHANDS_BUILD_GIT_SHA}"
+
+ENV AGENT_CANVAS_BUILD_GIT_SHA=${OPENHANDS_BUILD_GIT_SHA}
+ENV AGENT_CANVAS_BUILD_GIT_REF=${OPENHANDS_BUILD_GIT_REF}
+ENV AGENT_CANVAS_BASE_PATH=${VITE_BASE_PATH}
+ENV VITE_POSTHOG_API_KEY=${VITE_POSTHOG_API_KEY}
+
+USER root
+
+# Install system deps required by automation's transitive dependencies
+# (asyncpg needs libpq, which the agent-server base image may not include).
+RUN if command -v apt-get >/dev/null 2>&1; then \
+      apt-get update && \
+      apt-get install -y --no-install-recommends libpq-dev && \
+      rm -rf /var/lib/apt/lists/*; \
+    fi
+
+# Install automation server via pip.
+# Shared deps (openhands-sdk, fastapi, uvicorn, pydantic, httpx, …) are
+# already satisfied by the agent-server base image, so only automation-
+# specific packages (asyncpg, sqlalchemy, boto3, gcloud, …) are added.
+RUN uv pip install --system "openhands-automation==${AUTOMATION_VERSION}" 2>/dev/null \
+    || pip install --no-cache-dir "openhands-automation==${AUTOMATION_VERSION}"
+
+RUN if [ -n "${AGENT_SERVER_SDK_GIT_REF}" ]; then \
+      BASE_GIT_URL="git+https://github.com/OpenHands/software-agent-sdk@${AGENT_SERVER_SDK_GIT_REF}" && \
+      uv pip install --system --force-reinstall \
+        "${BASE_GIT_URL}#subdirectory=openhands-sdk" \
+        "${BASE_GIT_URL}#subdirectory=openhands-tools" \
+        "${BASE_GIT_URL}#subdirectory=openhands-workspace"; \
+    fi
+
+# Copy the frontend build output.
+# react-router.config.ts unpacks build/client/ into build/ for non-Vercel builds.
+COPY --from=frontend-build /build/build /opt/agent-canvas/frontend
+
+# Copy the static-server scripts and their production runtime deps.
+COPY scripts/static-server.mjs /opt/agent-canvas/static-server.mjs
+COPY scripts/proxy-utils.mjs /opt/agent-canvas/proxy-utils.mjs
+COPY --from=frontend-build /build/node_modules/httpxy /opt/agent-canvas/node_modules/httpxy
+COPY --from=frontend-build /build/node_modules/sirv /opt/agent-canvas/node_modules/sirv
+COPY --from=frontend-build /build/node_modules/@polka /opt/agent-canvas/node_modules/@polka
+COPY --from=frontend-build /build/node_modules/mrmime /opt/agent-canvas/node_modules/mrmime
+COPY --from=frontend-build /build/node_modules/totalist /opt/agent-canvas/node_modules/totalist
+
+# Copy the runtime-services-info builder (entrypoint.sh runs it as a CLI to
+# emit the agent's <RUNTIME_SERVICES> block; same builder the dev stack uses).
+COPY scripts/runtime-services-info.mjs /opt/agent-canvas/runtime-services-info.mjs
+
+# Persisted conversations created before the client_tools migration still
+# import canvas_ui_tool by qualname. Keep the compatibility module available;
+# new conversations define canvas_ui_control through a JSON client tool.
+COPY tools/ /opt/agent-canvas/tools/
+
+# Copy generated defaults.env (from config/defaults.json via config-gen stage)
+COPY --from=config-gen /tmp/defaults.env /opt/agent-canvas/defaults.env
+
+# Copy the entrypoint
+COPY docker/entrypoint.sh /opt/agent-canvas/entrypoint.sh
+RUN chmod +x /opt/agent-canvas/entrypoint.sh
+
+# Pre-create persistence directories with correct ownership so the
+# openhands user can write to them even when Docker creates anonymous
+# volumes (which default to root).
+RUN mkdir -p /home/openhands/.openhands/agent-canvas/conversations \
+             /home/openhands/.openhands/agent-canvas/bash_events \
+             /home/openhands/.openhands/automation \
+             /projects && \
+    chown -R openhands:openhands /home/openhands/.openhands /projects
+
+USER openhands
+
+# Persistence volumes:
+#   /home/openhands/.openhands — settings, secrets, conversations, automation DB
+#   /projects                  — user code the agent can read/edit
+# Bind-mount these for data to survive container restarts:
+#   docker run -v ~/.openhands:/home/openhands/.openhands -v ~/projects:/projects ...
+VOLUME ["/home/openhands/.openhands", "/projects"]
+
+# The entrypoint starts all services and the ingress proxy.
+# Port 8000 is the unified entry point.
+EXPOSE 8000
+
+ENTRYPOINT ["tini", "--", "/opt/agent-canvas/entrypoint.sh"]

docker/entrypoint.sh

@@ -0,0 +1,479 @@
+#!/usr/bin/env bash
+# ═══════════════════════════════════════════════════════════════════════════════
+# agent-canvas all-in-one entrypoint
+#
+# Starts three services (plus an optional fourth):
+#   1. Agent Server   on port $AGENT_SERVER_PORT  (default 18000)
+#   2. Automation     on port $AUTOMATION_PORT     (default 18001)
+#   3. Static server  on port $PORT               (default 8000)
+#      Routes /api/automation/* → automation, /api/* → agent-server,
+#      and serves the frontend static build for everything else.
+#   4. (Optional) Public-mode static server on $PUBLIC_MODE_PORT
+#      Same frontend, but with --auth-required (no baked session key).
+#      Used by auth-mode E2E tests. Only started when PUBLIC_MODE_PORT is set.
+#
+# Environment variables:
+#   PORT                 – Unified entry point port (default: 8000)
+#   AGENT_SERVER_PORT    – Internal agent-server port (default: 18000)
+#   AUTOMATION_PORT      – Internal automation port (default: 18001)
+#   AGENT_CANVAS_BASE_PATH – Static frontend mount path (default: /canvas)
+#   VSCODE_PORT          – Internal editor port (default: 8001). The image does
+#                          not EXPOSE it and the editor is reached through
+#                          VSCODE_BASE_PATH on $PORT, but openvscode-server
+#                          binds 0.0.0.0, so `docker run --network host` does
+#                          leave it directly reachable with only its connection
+#                          token in front of it.
+#   VSCODE_BASE_PATH     – Path prefix the editor is served under on $PORT
+#                          (default: /vscode). Exported to agent-server as
+#                          OH_VSCODE_BASE_PATH and routed by the static server.
+#                          agent-server's own OH_VSCODE_PORT / OH_VSCODE_BASE_PATH
+#                          take precedence over these aliases; whichever is set,
+#                          one effective pair drives both the editor process and
+#                          the proxy route.
+#   PUBLIC_MODE_PORT     – If set, starts a second static server on this port
+#                          with --auth-required (no session key injected)
+#   OH_SECRET_KEY        – Secret key for settings encryption (auto-generated
+#                          and persisted if not provided)
+#   OPENHANDS_AUTOMATION_API_KEY – Override automation backend auth key
+#                          (defaults to session API key — both backends
+#                          use the same `X-Session-API-Key` header)
+#   AUTOMATION_AGENT_SERVER_URL  – URL the automation service uses to reach the
+#                          agent-server (default: http://127.0.0.1:AGENT_SERVER_PORT).
+#                          Setting this enables local-mode auth so the session
+#                          API key is validated internally instead of against the
+#                          OpenHands cloud API.
+#   FILE_STORE             – Storage backend for automation tarballs (default: local).
+#                          Without this the automation backend may fall back to
+#                          S3/GCS which fails without cloud credentials.
+#   LOCAL_STORAGE_PATH     – Directory for local file storage (default: ~/.openhands/storage)
+#   AUTOMATION_BASE_URL    – Publicly-reachable base URL for the automation
+#                          service, used in callback URLs and injected into
+#                          sandboxes (default: http://127.0.0.1:$PORT).
+#                          Override in production when the external URL differs.
+#   AUTOMATION_WORKSPACE_BASE – Directory for automation run workspaces
+#                          (default: ~/.openhands/workspaces)
+#   Any agent-server or automation env vars are passed through.
+# ═══════════════════════════════════════════════════════════════════════════════
+set -uo pipefail
+
+log() { printf '[agent-canvas] %s\n' "$*"; }
+log_error() { printf '[agent-canvas] ERROR: %s\n' "$*" >&2; }
+
+# ── Load centralized defaults (generated from config/defaults.json at build) ─
+# shellcheck source=/dev/null
+if [ -f /opt/agent-canvas/defaults.env ]; then
+  # shellcheck disable=SC1091
+  . /opt/agent-canvas/defaults.env
+fi
+
+PORT="${PORT:-${CONFIG_PROXY_PORT:-8000}}"
+AGENT_SERVER_PORT="${AGENT_SERVER_PORT:-${CONFIG_AGENT_SERVER_PORT:-18000}}"
+AUTOMATION_PORT="${AUTOMATION_PORT:-${CONFIG_AUTOMATION_PORT:-18001}}"
+
+# The bundled editor is reached through a path prefix on the proxy port rather
+# than a published port of its own. The same prefix has to reach agent-server
+# (it launches openvscode-server with --server-base-path and advertises the
+# prefix from /api/vscode/url) and the static-server route table below, or the
+# advertised URL and the route serving it disagree.
+#
+# Two env var names reach the same setting: OH_VSCODE_PORT / OH_VSCODE_BASE_PATH
+# are agent-server's own documented variables, which a deployment may already
+# set and which this entrypoint passes through like any other OH_* var, while
+# VSCODE_PORT / VSCODE_BASE_PATH are this image's aliases. They collapse to one
+# effective pair here, before anything reads them — resolving them
+# independently would let `OH_VSCODE_BASE_PATH=/editor` move the editor without
+# moving the route, leaving the button pointing at a path the proxy never
+# serves.
+# >>> vscode-config: this block is extracted and executed by
+# >>> __tests__/scripts/docker-vscode-route-sync.test.ts — keep the markers.
+# The canvas mount is resolved here rather than alongside the ports above
+# because the collision guard below compares the two prefixes: keeping both
+# inside the extracted block is what lets that comparison be tested against the
+# real defaults instead of only against values a test injects.
+AGENT_CANVAS_BASE_PATH="${AGENT_CANVAS_BASE_PATH:-${CONFIG_CANVAS_BASE_PATH:-/canvas}}"
+VSCODE_PORT="${OH_VSCODE_PORT:-${VSCODE_PORT:-${CONFIG_VSCODE_PORT:-8001}}}"
+VSCODE_BASE_PATH="${OH_VSCODE_BASE_PATH:-${VSCODE_BASE_PATH:-${CONFIG_VSCODE_BASE_PATH:-/vscode}}}"
+
+# Accept "editor", "/editor" and "/editor/" alike: agent-server strips the
+# slashes when it builds the advertised URL, the static-server route table
+# needs the leading one, so settle on one spelling rather than one per use site.
+normalize_base_path() {
+  local p="$1"
+  while [ "${p#/}" != "$p" ]; do p="${p#/}"; done
+  while [ "${p%/}" != "$p" ]; do p="${p%/}"; done
+  printf '/%s' "$p"
+}
+VSCODE_BASE_PATH="$(normalize_base_path "$VSCODE_BASE_PATH")"
+if [ "$VSCODE_BASE_PATH" = "/" ]; then
+  log_error "VSCODE_BASE_PATH resolved to the site root — that would route the whole origin to the editor instead of the canvas. Set a prefix such as /vscode."
+  exit 1
+fi
+
+# The canvas mount gets the same treatment, for the same reason and with the
+# same function. static-server normalizes whatever `--base-path` it is handed
+# (`canvas` and `/canvas/` both mount at `/canvas`), so comparing a normalized
+# editor prefix against a raw canvas one below would let `AGENT_CANVAS_BASE_PATH=canvas`
+# with `OH_VSCODE_BASE_PATH=/canvas` past the collision guard and then land both
+# on `/canvas` — where the editor route, registered after the SPA mount, takes
+# the application over. Normalizing here rather than at the comparison keeps the
+# value passed to `--base-path` further down identical to the one guarded.
+AGENT_CANVAS_BASE_PATH="$(normalize_base_path "$AGENT_CANVAS_BASE_PATH")"
+
+# static-server keys its route table by prefix and the editor route is
+# registered last, so a prefix that collides with an earlier route silently
+# replaces it rather than failing: OH_VSCODE_BASE_PATH=/api would send every
+# API call to the editor port. Reject collisions and anything that is not a
+# plain single-segment path — '=' would be mis-split by the --route parser
+# (it cuts at the first '='), and whitespace, '?', '#' or '..' have no
+# meaningful reading as a route prefix.
+VSCODE_PATH_SEGMENT="${VSCODE_BASE_PATH#/}"
+case "$VSCODE_PATH_SEGMENT" in
+  */*)
+    log_error "VSCODE_BASE_PATH must be a single path segment (got '$VSCODE_BASE_PATH'). Use a prefix such as /vscode."
+    exit 1
+    ;;
+  .|..)
+    log_error "VSCODE_BASE_PATH must not be a relative path segment (got '$VSCODE_BASE_PATH'). Use a prefix such as /vscode."
+    exit 1
+    ;;
+  *[!A-Za-z0-9._-]*)
+    log_error "VSCODE_BASE_PATH may only contain letters, digits, '.', '_' and '-' (got '$VSCODE_BASE_PATH'). Use a prefix such as /vscode."
+    exit 1
+    ;;
+esac
+for reserved in /api /sockets /server_info /alive /health /ready /docs /redoc /openapi.json "${AGENT_CANVAS_BASE_PATH:-}"; do
+  if [ -n "$reserved" ] && [ "$VSCODE_BASE_PATH" = "$reserved" ]; then
+    log_error "VSCODE_BASE_PATH '$VSCODE_BASE_PATH' collides with an existing route and would take it over. Set a different prefix, such as /vscode."
+    exit 1
+  fi
+done
+
+# The port ends up in a proxy target URL, so a non-numeric value fails at the
+# first editor request instead of at startup. Catch it here.
+case "$VSCODE_PORT" in
+  ''|*[!0-9]*)
+    log_error "VSCODE_PORT must be a number (got '$VSCODE_PORT')."
+    exit 1
+    ;;
+esac
+
+export OH_VSCODE_PORT="$VSCODE_PORT"
+export OH_VSCODE_BASE_PATH="$VSCODE_BASE_PATH"
+# The single route string every static-server instance registers. Derived from
+# the exported pair above so the advertised URL and the route cannot diverge.
+VSCODE_ROUTE="${VSCODE_BASE_PATH}=http://127.0.0.1:${VSCODE_PORT}"
+# <<< vscode-config
+
+# Persistence paths — keep settings, conversations, bash history under a
+# single well-known directory that the VOLUME directive exposes.
+OPENHANDS_DIR="${HOME}/.openhands"
+STATE_DIR="${OPENHANDS_DIR}/${CONFIG_STATE_SUBDIR:-agent-canvas}"
+export OH_PERSISTENCE_DIR="${OH_PERSISTENCE_DIR:-${OPENHANDS_DIR}}"
+export OH_CONVERSATIONS_PATH="${OH_CONVERSATIONS_PATH:-${OPENHANDS_DIR}/${CONFIG_CONVERSATIONS:-agent-canvas/conversations}}"
+export OH_BASH_EVENTS_DIR="${OH_BASH_EVENTS_DIR:-${OPENHANDS_DIR}/${CONFIG_BASH_EVENTS:-agent-canvas/bash_events}}"
+
+# OH_SECRET_KEY is required for settings/secrets encryption. Without it the
+# agent-server refuses to return encrypted secrets → conversation creation
+# fails with a 503.  Auto-generate and persist (just like the session API key)
+# so the image never runs with a known default.
+SECRET_KEY_FILE="${STATE_DIR}/secret-key.txt"
+if [ -z "${OH_SECRET_KEY:-}" ]; then
+  if [ -f "$SECRET_KEY_FILE" ]; then
+    OH_SECRET_KEY="$(cat "$SECRET_KEY_FILE")"
+  else
+    OH_SECRET_KEY="$(head -c 32 /dev/urandom | od -An -tx1 | tr -d ' \n')"
+    mkdir -p "$(dirname "$SECRET_KEY_FILE")"
+    printf '%s' "$OH_SECRET_KEY" > "$SECRET_KEY_FILE"
+    chmod 600 "$SECRET_KEY_FILE"
+    log "Generated OH_SECRET_KEY (persisted to $SECRET_KEY_FILE)"
+  fi
+fi
+export OH_SECRET_KEY
+
+# API key — generate one if not provided so the image doesn't run wide-open
+# by default. LOCAL_BACKEND_API_KEY is the single user-facing env var.
+# Persisted so restarts reuse the same key.
+API_KEY_FILE="${STATE_DIR}/api-key.txt"
+
+if [ -z "${LOCAL_BACKEND_API_KEY:-}" ] && [ -z "${OH_SESSION_API_KEYS_0:-}" ]; then
+  if [ -f "$API_KEY_FILE" ]; then
+    LOCAL_BACKEND_API_KEY="$(cat "$API_KEY_FILE")"
+  else
+    LOCAL_BACKEND_API_KEY="$(head -c 32 /dev/urandom | od -An -tx1 | tr -d ' \n')"
+    mkdir -p "$(dirname "$API_KEY_FILE")"
+    printf '%s' "$LOCAL_BACKEND_API_KEY" > "$API_KEY_FILE"
+    chmod 600 "$API_KEY_FILE"
+    log "Generated API key (persisted to $API_KEY_FILE)"
+  fi
+  export OH_SESSION_API_KEYS_0="$LOCAL_BACKEND_API_KEY"
+fi
+
+# Both backends share the same API key value and the same `X-Session-API-Key`
+# header for authentication.  Default OPENHANDS_AUTOMATION_API_KEY to the
+# API key so a single credential secures the whole stack.
+EFFECTIVE_SESSION_KEY="${OH_SESSION_API_KEYS_0:-${LOCAL_BACKEND_API_KEY:-}}"
+if [ -z "$EFFECTIVE_SESSION_KEY" ]; then
+  log "ERROR: No session API key available — cannot configure automation auth"
+  exit 1
+fi
+export OPENHANDS_AUTOMATION_API_KEY="${OPENHANDS_AUTOMATION_API_KEY:-${EFFECTIVE_SESSION_KEY}}"
+export AUTOMATION_LOCAL_API_KEY="${AUTOMATION_LOCAL_API_KEY:-${EFFECTIVE_SESSION_KEY}}"
+export AUTOMATION_AGENT_SERVER_API_KEY="${AUTOMATION_AGENT_SERVER_API_KEY:-${EFFECTIVE_SESSION_KEY}}"
+export OPENHANDS_REMOTE_WS_READY_REQUIRED="${OPENHANDS_REMOTE_WS_READY_REQUIRED:-false}"
+if [ -z "${AUTOMATION_POSTHOG_API_KEY:-}" ]; then
+  if [ -n "${VITE_POSTHOG_API_KEY:-}" ]; then
+    export AUTOMATION_POSTHOG_API_KEY="$VITE_POSTHOG_API_KEY"
+  elif [ "${VITE_DO_NOT_TRACK:-}" != "1" ]; then
+    export AUTOMATION_POSTHOG_API_KEY="${CONFIG_POSTHOG_API_KEY:-}"
+  fi
+fi
+if [ -n "${AUTOMATION_POSTHOG_API_KEY:-}" ]; then
+  export AUTOMATION_POSTHOG_HOST="${AUTOMATION_POSTHOG_HOST:-${VITE_POSTHOG_HOST:-${CONFIG_POSTHOG_HOST:-}}}"
+fi
+
+# Configure product analytics for the agent-server. The SDK uses its own
+# OH_TELEMETRY_* variables, so mirror the same Canvas/PostHog defaults used by
+# the frontend and automation backend while preserving explicit operator
+# overrides. Consent stays in persisted settings, where the backend/UI owns it.
+if [ "${VITE_DO_NOT_TRACK:-}" = "1" ]; then
+  export DO_NOT_TRACK="${DO_NOT_TRACK:-1}"
+fi
+
+if [ -z "${OH_TELEMETRY_POSTHOG_API_KEY:-}" ]; then
+  if [ -n "${VITE_POSTHOG_API_KEY:-}" ]; then
+    export OH_TELEMETRY_POSTHOG_API_KEY="$VITE_POSTHOG_API_KEY"
+  elif [ "${DO_NOT_TRACK:-}" != "1" ]; then
+    export OH_TELEMETRY_POSTHOG_API_KEY="${CONFIG_POSTHOG_API_KEY:-}"
+  fi
+fi
+
+if [ -z "${OH_TELEMETRY_EXPORTER:-}" ] && [ -n "${OH_TELEMETRY_POSTHOG_API_KEY:-}" ]; then
+  export OH_TELEMETRY_EXPORTER="posthog"
+fi
+
+if [ "${OH_TELEMETRY_EXPORTER:-}" = "posthog" ] && [ -n "${OH_TELEMETRY_POSTHOG_API_KEY:-}" ]; then
+  export OH_TELEMETRY_POSTHOG_HOST="${OH_TELEMETRY_POSTHOG_HOST:-${VITE_POSTHOG_HOST:-${CONFIG_POSTHOG_HOST:-}}}"
+fi
+
+# AGENT_SERVER_URL — needed by automation sandbox callbacks.
+export AGENT_SERVER_URL="${AGENT_SERVER_URL:-http://127.0.0.1:${AGENT_SERVER_PORT}}"
+
+# AUTOMATION_AGENT_SERVER_URL — the URL the automation service uses to reach
+# the agent-server REST API (tarball upload, bash dispatch, auth key minting).
+# When set, ServiceSettings.is_local_mode returns True, enabling local API key
+# authentication. Without this, the automation server falls back to validating
+# keys against the OpenHands cloud API (app.all-hands.dev), which returns 401
+# for locally-generated session keys.
+export AUTOMATION_AGENT_SERVER_URL="${AUTOMATION_AGENT_SERVER_URL:-http://127.0.0.1:${AGENT_SERVER_PORT}}"
+
+# Keep the legacy canvas_ui_tool module importable when the agent-server restores
+# conversations whose persisted metadata still references its module qualname.
+# It is also imported at startup below (--import-modules) so its builtin
+# FinishTool registration lets automation runs resolve the tool on their
+# remote conversations (see the note at the bottom of tools/canvas_ui_tool.py).
+export OH_EXTRA_PYTHON_PATH="${OH_EXTRA_PYTHON_PATH:-/opt/agent-canvas/tools}"
+AGENT_SERVER_IMPORT_MODULES="canvas_ui_tool"
+
+# Track child PIDs so we can clean up on exit.
+PIDS=()
+
+cleanup() {
+  log "Shutting down..."
+  for pid in "${PIDS[@]}"; do
+    kill "$pid" 2>/dev/null || true
+  done
+  wait 2>/dev/null || true
+  exit 0
+}
+trap cleanup EXIT SIGINT SIGTERM
+
+# ── 1. Start Agent Server ────────────────────────────────────────────────────
+log "Starting agent-server on port $AGENT_SERVER_PORT..."
+
+if command -v openhands-agent-server >/dev/null 2>&1; then
+  # Binary build (production image)
+  openhands-agent-server --port "$AGENT_SERVER_PORT" \
+    --import-modules "$AGENT_SERVER_IMPORT_MODULES" &
+elif [ -x /agent-server/.venv/bin/python ]; then
+  # Source build (development image)
+  /agent-server/.venv/bin/python -m openhands.agent_server --port "$AGENT_SERVER_PORT" \
+    --import-modules "$AGENT_SERVER_IMPORT_MODULES" &
+else
+  log_error "Cannot find agent-server binary or source venv."
+  exit 1
+fi
+PIDS+=($!)
+
+# ── 2. Start Automation Server ───────────────────────────────────────────────
+log "Starting automation server on port $AUTOMATION_PORT..."
+
+# File storage — use local filesystem unless the user has configured cloud
+# storage.  Without FILE_STORE=local the automation backend may fall back
+# to a cloud provider (S3/GCS) which will fail without credentials, causing
+# tarball-based presets (preset/prompt, preset/plugin) to silently error.
+export FILE_STORE="${FILE_STORE:-local}"
+export LOCAL_STORAGE_PATH="${LOCAL_STORAGE_PATH:-${OPENHANDS_DIR}/storage}"
+mkdir -p "$LOCAL_STORAGE_PATH"
+
+# AUTOMATION_BASE_URL — the publicly-reachable base URL for the automation
+# service.  Appended to callback URLs and injected into each sandbox as
+# AUTOMATION_API_URL.  Defaults to the unified ingress.
+export AUTOMATION_BASE_URL="${AUTOMATION_BASE_URL:-http://127.0.0.1:${PORT}}"
+
+# AUTOMATION_WORKSPACE_BASE — where automation runs unpack tarballs.
+export AUTOMATION_WORKSPACE_BASE="${AUTOMATION_WORKSPACE_BASE:-${OPENHANDS_DIR}/workspaces}"
+mkdir -p "$AUTOMATION_WORKSPACE_BASE"
+
+# Default to SQLite so the automation server works out of the box without
+# an external PostgreSQL instance. Users can override AUTOMATION_DB_URL to
+# point at a real Postgres for production deployments.
+if [ -z "${AUTOMATION_DB_URL:-}" ]; then
+  AUTOMATION_DB_FILE="${OPENHANDS_DIR}/${CONFIG_AUTOMATION_DB:-automation/automations.db}"
+  mkdir -p "$(dirname "$AUTOMATION_DB_FILE")"
+  export AUTOMATION_DB_URL="sqlite+aiosqlite:///${AUTOMATION_DB_FILE}"
+  log "Using SQLite database: $AUTOMATION_DB_URL"
+fi
+
+# The automation server uses uvicorn. Set AUTOMATION_PORT via its CLI.
+if command -v uvicorn >/dev/null 2>&1; then
+  uvicorn openhands.automation.app:app \
+    --host 0.0.0.0 \
+    --port "$AUTOMATION_PORT" &
+  PIDS+=($!)
+elif python -c "import openhands.automation" 2>/dev/null; then
+  python -m uvicorn openhands.automation.app:app \
+    --host 0.0.0.0 \
+    --port "$AUTOMATION_PORT" &
+  PIDS+=($!)
+else
+  log "WARNING: Automation server not found, skipping."
+fi
+
+# ── 3. Wait for backends to be ready ─────────────────────────────────────────
+wait_for_port() {
+  local port=$1 name=$2 max_wait=${3:-30}
+  local elapsed=0
+  while ! (echo >/dev/tcp/127.0.0.1/"$port") 2>/dev/null; do
+    sleep 1
+    elapsed=$((elapsed + 1))
+    if [ "$elapsed" -ge "$max_wait" ]; then
+      log "WARNING: $name on port $port did not become ready within ${max_wait}s"
+      return 1
+    fi
+  done
+  log "$name is ready on port $port"
+}
+
+wait_for_port "$AGENT_SERVER_PORT" "Agent Server" 60 &
+WAIT_PID1=$!
+wait_for_port "$AUTOMATION_PORT" "Automation Server" 60 &
+WAIT_PID2=$!
+wait "$WAIT_PID1" "$WAIT_PID2"
+
+# ── 4. Start static server (frontend + proxy) ────────────────────────────────
+log "Starting frontend + proxy on port $PORT..."
+
+# Describe the local runtime services so the frontend can populate the agent's
+# <RUNTIME_SERVICES> system-prompt block (without it the agent does not know how
+# to reach the local automation backend and falls back to the cloud API). These
+# URLs are runtime config (overridable at `docker run`), so build the JSON here
+# from the sandbox-facing URLs the entrypoint already exports. static-server.mjs
+# appends it to /server_info as runtime_services and also injects the legacy
+# window global for older frontend bundles.
+RUNTIME_SERVICES_INFO="$(node /opt/agent-canvas/runtime-services-info.mjs \
+  --mode docker \
+  --agent-host-alias 127.0.0.1 \
+  --agent-server-url "$AGENT_SERVER_URL" \
+  --automation-url "$AUTOMATION_BASE_URL")"
+
+# EFFECTIVE_SESSION_KEY is set above from LOCAL_BACKEND_API_KEY or the persisted api-key.txt
+node /opt/agent-canvas/static-server.mjs \
+  --port "$PORT" \
+  --host :: \
+  --dir /opt/agent-canvas/frontend \
+  --base-path "$AGENT_CANVAS_BASE_PATH" \
+  --session-api-key "$EFFECTIVE_SESSION_KEY" \
+  --runtime-services-info "$RUNTIME_SERVICES_INFO" \
+  --route "/api/automation=http://127.0.0.1:${AUTOMATION_PORT}" \
+  --route "/api=http://127.0.0.1:${AGENT_SERVER_PORT}" \
+  --route "/server_info=http://127.0.0.1:${AGENT_SERVER_PORT}" \
+  --route "/sockets=http://127.0.0.1:${AGENT_SERVER_PORT}" \
+  --route "/alive=http://127.0.0.1:${AGENT_SERVER_PORT}" \
+  --route "/health=http://127.0.0.1:${AGENT_SERVER_PORT}" \
+  --route "/ready=http://127.0.0.1:${AGENT_SERVER_PORT}" \
+  --route "/docs=http://127.0.0.1:${AGENT_SERVER_PORT}" \
+  --route "/redoc=http://127.0.0.1:${AGENT_SERVER_PORT}" \
+  --route "/openapi.json=http://127.0.0.1:${AGENT_SERVER_PORT}" \
+  --route "$VSCODE_ROUTE" \
+  --vscode-base-path "$VSCODE_BASE_PATH" \
+  --no-referrer-prefix "$VSCODE_BASE_PATH" &
+STATIC_PID=$!
+PIDS+=("$STATIC_PID")
+
+# ── 5. (Optional) Public-mode static server ─────────────────────────────────
+# When PUBLIC_MODE_PORT is set, start a second static-server instance that
+# serves the same frontend WITHOUT injecting the session key into the HTML
+# (--auth-required). This is used by auth-mode E2E tests to verify the
+# ApiKeyEntryScreen gate, key rotation recovery, etc.
+#
+# Neither the editor route nor --vscode-base-path is registered here, and the
+# pair is deliberate: the route is what would serve the editor, and the flag is
+# what tells the frontend this origin can. Omitting only the route would leave
+# the control rendering and falling through to the SPA, because the agent-server
+# it shares with the main instance still reports the editor as available.
+#
+# --auth-required only
+# controls whether the session key is injected into the served HTML; the
+# dispatcher matches routes before it reaches that flag, so proxied paths are
+# not gated by it. The routes above are safe on that footing because
+# agent-server enforces the session key itself, but the editor's own
+# credential is the connection token agent-server puts in the query string —
+# and agent-server derives that token from session_api_keys[0], so it is the
+# same secret that authenticates /api. Registering the route here would put
+# that secret in a browser-navigable URL on the origin that exists precisely
+# to test the unauthenticated case, where it would persist in history and
+# leak by Referer from the workbench's own subresources.
+#
+# The token's scope is upstream's to fix and is tracked in
+# OpenHands/software-agent-sdk#4317; if the editor gets a credential of its own,
+# this exclusion and the --no-referrer-prefix below can both be revisited.
+if [ -n "${PUBLIC_MODE_PORT:-}" ]; then
+  log "Starting public-mode frontend on port $PUBLIC_MODE_PORT (--auth-required)..."
+  node /opt/agent-canvas/static-server.mjs \
+    --port "$PUBLIC_MODE_PORT" \
+    --host :: \
+    --dir /opt/agent-canvas/frontend \
+    --base-path "$AGENT_CANVAS_BASE_PATH" \
+    --auth-required \
+    --runtime-services-info "$RUNTIME_SERVICES_INFO" \
+    --route "/api/automation=http://127.0.0.1:${AUTOMATION_PORT}" \
+    --route "/api=http://127.0.0.1:${AGENT_SERVER_PORT}" \
+    --route "/server_info=http://127.0.0.1:${AGENT_SERVER_PORT}" \
+    --route "/sockets=http://127.0.0.1:${AGENT_SERVER_PORT}" \
+    --route "/alive=http://127.0.0.1:${AGENT_SERVER_PORT}" \
+    --route "/health=http://127.0.0.1:${AGENT_SERVER_PORT}" \
+    --route "/ready=http://127.0.0.1:${AGENT_SERVER_PORT}" \
+    --route "/docs=http://127.0.0.1:${AGENT_SERVER_PORT}" \
+    --route "/redoc=http://127.0.0.1:${AGENT_SERVER_PORT}" \
+    --route "/openapi.json=http://127.0.0.1:${AGENT_SERVER_PORT}" &
+  PIDS+=($!)
+fi
+
+log "All services started. Unified entry point: http://0.0.0.0:${PORT}/"
+
+# Keep the container alive while the static-server (ingress) is running.
+# Backend crashes (agent-server, automation) are tolerated — the proxy
+# returns 502 for downed routes, matching the non-Docker path where each
+# service is an independent host process.
+#
+# Pattern: `sleep & wait $!` makes `wait` (a bash builtin) the foreground
+# operation.  Unlike a bare `sleep`, the builtin `wait` is interrupted
+# immediately when a trapped signal (SIGTERM/SIGINT) arrives, so cleanup()
+# fires without delay.  cleanup() calls `exit 0` to terminate after the
+# trap returns.  The loop re-checks the static-server PID every 10 s so the
+# container exits promptly if the ingress process dies on its own.
+while kill -0 "$STATIC_PID" 2>/dev/null; do
+  sleep 10 & wait $!
+done
+log_error "Static server (PID $STATIC_PID) exited"
+exit 1

docs/SELF_HOSTING.md

@@ -0,0 +1,286 @@
+# Self-Hosting Agent Canvas on a Virtual Machine
+
+This guide walks through running Agent Canvas on a virtual machine (VM) so you
+can reach it from anywhere via a browser.
+
+> [!WARNING]
+> Agent Canvas drives an agent that can read and write the filesystem of the
+> machine it runs on, execute shell commands, and reach the network. Anyone who
+> can talk to the agent server can do the same. **Treat the VM as you would any
+> machine that holds production credentials**, and lock it down before exposing
+> it to the public internet.
+
+## Quickstart
+
+1. **Provision a machine** — a cloud VM or dedicated hardware (Mac Mini, NUC, etc.)
+2. **Secure the machine** — lock down the network firewall
+3. **Run Agent Canvas** — generate a key with `openssl rand -base64 32`, then `export LOCAL_BACKEND_API_KEY=<key>` and `npx @openhands/agent-canvas --public`
+4. **(Optional) Get a domain** — point a domain at the machine with nginx + Let's Encrypt for TLS
+5. **(Optional) Connect locally** — add the remote as a backend in your local Agent Canvas
+
+## Details
+
+The deployment model:
+
+```mermaid
+flowchart LR
+    user(["🧑 You"])
+    subgraph vm["Your VM (single host)"]
+        direction LR
+        nginx["nginx :443<br/>(TLS)"]
+        ingress["Ingress proxy<br/>127.0.0.1:8000"]
+        static["Static server<br/>:3001"]
+        agent["Agent server<br/>:18000<br/>(LOCAL_BACKEND_API_KEY)"]
+        automation["Automation backend<br/>:18001"]
+        nginx --> ingress
+        ingress -- "/*" --> static
+        ingress -- "/api/*, /sockets" --> agent
+        ingress -- "/api/automation/*" --> automation
+    end
+    user -- "HTTPS / 443" --> nginx
+```
+
+`npx @openhands/agent-canvas --public` spins up the static frontend server,
+the agent server, and the automation backend, fronted by an ingress proxy on
+`127.0.0.1:8000` that routes by path. nginx only needs to know about that
+single ingress port.
+
+The `--public` flag enables **public mode**: the API key is _not_ baked into
+the frontend. Instead, users see an API key entry screen when they first load
+the UI and must paste the `LOCAL_BACKEND_API_KEY` to proceed.
+
+The defenses layered on top of this:
+
+1. **Cloud / network firewall (step 2)** — by default nothing inbound is
+   reachable except SSH from your IP. If you do step 4, you additionally open
+   80 and 443 (ideally still restricted to your IP allow-list on 443).
+2. **`LOCAL_BACKEND_API_KEY` + public mode (step 3)** — every `/api/*` call
+   must carry a matching `X-Session-API-Key` header, and the UI requires
+   users to enter the key before they can interact with the agent.
+
+## 1. Provision a machine
+
+Any always-on Linux (or macOS) host with a stable network connection will do:
+
+- **A cloud VM** — DigitalOcean, AWS EC2, GCP, Hetzner, Linode, etc.
+  Ubuntu 24.04 LTS is a good default. 2 vCPU / 4 GB RAM is plenty for a
+  single user.
+- **Dedicated hardware** — a Mac Mini, an Intel NUC, a spare laptop.
+  Keep in mind that anything reachable from your LAN is part of the threat
+  model.
+
+## 2. Secure the machine
+
+> [!IMPORTANT]
+> Do this **before** you start the agent server for the first time.
+
+The default posture should be: **nothing inbound is reachable from the public
+internet** except SSH (and only from your own IP). All services bind to
+`127.0.0.1` (see step 3), but the network firewall is what guarantees no one
+else can reach them even if something binds wrong.
+
+Restrict inbound traffic at the cloud-provider / network level (DigitalOcean
+Cloud Firewall, AWS Security Group, GCP firewall rule, etc.):
+
+- **Inbound 22 (SSH)** — restrict to your own IP / VPN CIDR.
+- **Everything else** — drop. The ingress port (`:8000`), agent server
+  (`:18000`), automation backend (`:18001`), and static server (`:3001`)
+  must not be reachable from outside the host.
+
+At this point your machine is reachable only over SSH. That's enough to run
+the agent (step 3) and access the UI through an SSH tunnel. If you also want
+to reach it from a browser without tunneling, you'll open ports 80 and 443
+in step 4.
+
+> [!NOTE]
+> **The bundled editor shares the canvas's browser origin.** OpenVSCode is
+> served under a path prefix (`/vscode` by default) on the proxy port rather
+> than on a published port of its own — that is what keeps the deployment to a
+> single port, but a path prefix routes requests, it does not isolate them.
+> Script running anywhere on that origin, including editor content reached
+> through an extension or a compromised asset, can read the canvas's
+> `localStorage`, which holds the SESSION API key of _every_ backend registered
+> in that browser. Tracked in
+> [#16492](https://github.com/OpenHands/OpenHands/issues/16492).
+
+## 3. Run Agent Canvas
+
+Install the prerequisites on the machine. On Ubuntu:
+
+```bash
+apt-get update
+apt-get install -y curl git
+# Node.js 22.x (use nvm, asdf, or NodeSource — whatever you prefer)
+# uv (for the agent-server uvx runtime):
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+On macOS (Mac Mini, etc.) install Node and `uv` via `brew` instead.
+
+Start Agent Canvas in public mode:
+
+```bash
+export LOCAL_BACKEND_API_KEY=$(openssl rand -base64 32)   # generate once; store securely
+npx @openhands/agent-canvas --public
+```
+
+Using `export` keeps the key out of the process list (`ps aux`). The
+`openssl rand -base64 32` command generates a cryptographically random
+256-bit key — copy the printed value somewhere safe before proceeding.
+
+This single command downloads the latest release, starts the agent server,
+the automation backend, and the static frontend, and fronts them with an
+ingress proxy on `127.0.0.1:8000`.
+
+To keep the service running after your SSH session ends, use a process manager.
+
+**Option A — tmux (quick):**
+
+```bash
+export LOCAL_BACKEND_API_KEY=<your-saved-key>
+tmux new-session -d -s canvas 'npx @openhands/agent-canvas --public'
+# Reconnect later with: tmux attach -t canvas
+```
+
+**Option B — systemd (recommended for long-term deployments):**
+
+Create `/etc/systemd/system/agent-canvas.service`:
+
+```ini
+[Unit]
+Description=Agent Canvas
+After=network.target
+
+[Service]
+Environment=LOCAL_BACKEND_API_KEY=<your-key>
+ExecStart=npx @openhands/agent-canvas --public
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Then enable and start the unit:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now agent-canvas
+```
+
+> [!WARNING]
+> The agent server runs **directly on the host** with full access to the
+> machine's filesystem, environment, and network. The firewall (step 2) and
+> the `LOCAL_BACKEND_API_KEY` are what stop a stranger from getting that
+> same access.
+
+The `--public` flag means anyone who opens the UI must enter the API key
+before they can use it. Without `--public`, the key is auto-injected into
+the frontend (convenient for local-only use, but unsafe for a
+publicly-reachable deployment).
+
+## 4. (Optional) Get a domain and put nginx + Let's Encrypt in front
+
+If you want to reach the UI from a browser without an SSH tunnel — for
+example, from a phone or a machine you can't easily forward ports from —
+point a domain at the host and front it with nginx + TLS. nginx terminates
+TLS and forwards to the ingress on `127.0.0.1:8000`.
+
+### Point a domain at the machine
+
+Create an `A` record pointing to the machine's public IPv4 — for example
+`canvas.example.com`. Verify DNS has propagated:
+
+```bash
+dig +short canvas.example.com
+```
+
+### Open ports 80 and 443
+
+Go back to your network firewall and additionally allow inbound:
+
+- **Inbound 80 (HTTP)** — open to `0.0.0.0/0` (required for Let's Encrypt
+  HTTP-01 challenges). nginx will redirect all traffic to HTTPS.
+- **Inbound 443 (HTTPS)** — restrict to your own IP / VPN CIDR if you can.
+  If you need it world-open (e.g. you roam often), `LOCAL_BACKEND_API_KEY`
+  is your primary defense.
+
+### Install nginx and certbot
+
+```bash
+apt-get install -y nginx certbot python3-certbot-nginx
+```
+
+### nginx site config
+
+Drop this at `/etc/nginx/sites-available/canvas.example.com`, replacing
+`canvas.example.com` with your domain:
+
+```nginx
+server {
+    listen 80;
+    listen [::]:80;
+    server_name canvas.example.com;
+
+    location /.well-known/acme-challenge/ {
+        root /var/www/html;
+    }
+
+    location / {
+        proxy_pass http://127.0.0.1:8000;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # WebSocket / SSE support — required for live agent events.
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_read_timeout 3600s;
+        proxy_send_timeout 3600s;
+    }
+}
+```
+
+Enable, test, and issue a certificate:
+
+```bash
+ln -sf /etc/nginx/sites-available/canvas.example.com \
+       /etc/nginx/sites-enabled/canvas.example.com
+nginx -t && systemctl reload nginx
+
+certbot --nginx -d canvas.example.com \
+    --non-interactive --agree-tos \
+    --email you@example.com \
+    --redirect
+```
+
+`certbot` adds the `listen 443 ssl` block, a 301 redirect from HTTP to
+HTTPS, and installs a systemd timer for auto-renewal.
+
+### Verify
+
+```bash
+curl -I https://canvas.example.com/      # → 200 (shows API key entry screen)
+curl -I http://canvas.example.com/       # → 301 to https
+```
+
+If you see `502 Bad Gateway`, the app on `127.0.0.1:8000` is down — check
+whether the `npx` process is still running.
+
+Open `https://canvas.example.com/` in a browser, enter your
+`LOCAL_BACKEND_API_KEY`, and confirm that you land in Agent Canvas.
+
+## 5. (Optional) Connect your local Agent Canvas to the remote machine
+
+If you already run Agent Canvas locally, you can register the remote machine
+as an additional backend and switch between local and remote from the UI.
+
+1. In your local Agent Canvas, open **Manage backends** → **Add a backend**:
+   - **Host Name** — anything memorable, e.g. `my-vm`.
+   - **Host** — the URL from step 4, e.g. `https://canvas.example.com`.
+     If using an SSH tunnel instead, use `http://localhost:8000`.
+   - **Session API key** — the `LOCAL_BACKEND_API_KEY` you chose in step 3.
+2. Save. The new backend should show as "Connected". Pick it from the
+   backend switcher to talk to the remote machine.

docs/TESTING_MATRIX.md

@@ -0,0 +1,97 @@
+# Agent Canvas — Testing Matrix
+
+**Priority key:** P0 = must pass before any release · P1 = must pass before GA · P2 = best-effort
+
+---
+
+## Install × OS × Agent
+
+Each cell = smoke test: install → onboard → start conversation → agent replies.
+
+| | **macOS** | **Linux** | **Windows** |
+|---|:---:|:---:|:---:|
+| **npm — OpenHands** | ☐ | ☐ | ☐ |
+| **npm — Claude Code** | ☐ | ☐ | ☐ |
+| **npm — Codex** | ☐ | ☐ | ☐ |
+| **npm — Gemini CLI** | ☐ | ☐ | ☐ |
+| **npm — Custom ACP** | ☐ | ☐ | ☐ |
+| **Docker — OpenHands** | ☐ | ☐ | ☐ |
+| **Docker — Claude Code** | ☐ | ☐ | ☐ |
+| **Docker — Codex** | ☐ | ☐ | ☐ |
+| **Docker — Gemini CLI** | ☐ | ☐ | ☐ |
+| **Docker — Custom ACP** | ☐ | ☐ | ☐ |
+
+---
+
+## Automations × Install × Agent
+
+Requires full stack (automation backend running).
+
+| | **npm** | **Docker** |
+|---|:---:|:---:|
+| **OpenHands** | ✅ P0 | ✅ P0 |
+| **Claude Code** | ✅ P1 | ✅ P1 |
+| **Codex** | ✅ P1 | ✅ P1 |
+| **Gemini CLI** | ✅ P2 | ✅ P2 |
+
+Each cell = create automation → dispatch run → run reaches COMPLETED → conversation link works.
+
+---
+
+## Auth Modes
+
+| | **npm** | **Docker** |
+|---|:---:|:---:|
+| **Local (auto-generated key)** | ✅ P0 | ✅ P0 |
+| **Public (`--public` + user key)** | ✅ P1 | ✅ P1 |
+
+---
+
+## Feature Checklist
+
+### npm
+
+| Feature | OpenHands | Claude Code | Codex | Gemini CLI |
+|---|:---:|:---:|:---:|:---:|
+| Onboarding | ☐ | ☐ | ☐ | ☐ |
+| Conversation — start, resume, history | ☐ | ☐ | ☐ | ☐ |
+| Terminal tool | ☐ | ☐ | ☐ | ☐ |
+| File editor tool | ☐ | ☐ | ☐ | ☐ |
+| Browser tool | ☐ | ☐ | ☐ | ☐ |
+| LLM profiles — create / switch | ☐ | — | — | — |
+| Secrets — add / delete / forwarded | ☐ | ☐ | ☐ | ☐ |
+| Automations — create, dispatch, COMPLETED | ☐ | ☐ | ☐ | ☐ |
+| Files tab + Changes/diff tab | ☐ | ☐ | ☐ | ☐ |
+| MCP server install | ☐ | ☐ | ☐ | ☐ |
+| Image upload in chat | ☐ | ☐ | ☐ | ☐ |
+| Key rotation | ☐ | ☐ | ☐ | ☐ |
+
+### Docker
+
+| Feature | OpenHands | Claude Code | Codex | Gemini CLI |
+|---|:---:|:---:|:---:|:---:|
+| Onboarding | ☐ | ☐ | ☐ | ☐ |
+| Conversation — start, resume, history | ☐ | ☐ | ☐ | ☐ |
+| Terminal tool | ☐ | ☐ | ☐ | ☐ |
+| File editor tool | ☐ | ☐ | ☐ | ☐ |
+| Browser tool | ☐ | ☐ | ☐ | ☐ |
+| LLM profiles — create / switch | ☐ | — | — | — |
+| Secrets — add / delete / forwarded | ☐ | ☐ | ☐ | ☐ |
+| Automations — create, dispatch, COMPLETED | ☐ | ☐ | ☐ | ☐ |
+| Files tab + Changes/diff tab | ☐ | ☐ | ☐ | ☐ |
+| MCP server install | ☐ | ☐ | ☐ | ☐ |
+| Image upload in chat | ☐ | ☐ | ☐ | ☐ |
+| Key rotation | ☐ | ☐ | ☐ | ☐ |
+
+---
+
+## Automated Coverage
+
+| Suite | Install | OS | Agents | Automations |
+|---|---|---|---|---|
+| `vitest` (unit) | — | Linux | — | partial |
+| `test:e2e:mock-llm` | npm | Linux | OpenHands, ACP (mock) | ✅ full |
+| `test:e2e:mock-llm:docker` | Docker | Linux | OpenHands, ACP (mock) | ✅ full |
+| `test:e2e:live` | npm | Linux | OpenHands | ❌ |
+
+**Not yet covered by CI:** real ACP credentials (Claude Code / Codex / Gemini), macOS, public auth mode, subscription login paths, Windows.

docs/architecture.md

@@ -0,0 +1,82 @@
+# Agent Canvas architecture
+
+Agent Canvas is a React and TypeScript frontend for running and monitoring OpenHands agents across local, remote, and hosted environments. It is adapted from the OpenHands frontend to talk directly to the OpenHands Agent Server and related automation services.
+
+## System boundaries
+
+Agent Canvas is responsible for:
+
+- Rendering the agent conversation, terminal, browser, files, settings, and automation UI.
+- Managing frontend state for conversations, backend selection, settings, profiles, and local metadata.
+- Translating UI actions into OpenHands Agent Server API calls.
+- Packaging the UI both as a standalone app and as library entrypoints for host applications.
+
+Agent Canvas is not responsible for:
+
+- Executing agent actions directly.
+- Providing the sandbox or workspace isolation layer.
+- Hosting LLM provider credentials outside the configured backend.
+- Running scheduled or event-triggered automations without an automation backend.
+
+## Runtime services
+
+The primary backend is the [OpenHands Agent Server](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-agent-server/openhands/agent_server). Agent Canvas can connect to one or more Agent Server instances and switch between them from the UI.
+
+Optional runtime services include:
+
+- An ingress service that routes frontend, Agent Server, and automation traffic behind one local origin.
+- An Automation Server for scheduled or event-triggered agent runs.
+- OpenHands Cloud APIs for hosted sandbox and organization workflows.
+
+Agent Canvas stack launchers expose runtime service information through the backend `/server_info.runtime_services` field. The frontend forwards that backend-provided information into new conversations as an agent context suffix so agents can use the correct URLs instead of guessing ports.
+
+## Frontend modules
+
+The most important source areas are:
+
+- `src/api/`: service adapters for Agent Server, cloud, settings, git, skills, automations, and backend registry behavior.
+- `src/components/`: route and feature UI, including conversation, chat, browser, files, settings, backend, automation, and onboarding components.
+- `src/hooks/`: reusable React Query, state, and feature hooks.
+- `src/stores/`: Zustand state stores for conversation and UI state.
+- `src/i18n/`: translation resources and generated bundles.
+- `src/mocks/`: MSW handlers for mock-mode development and tests.
+- `bin/` and `scripts/`: CLI and development stack launchers.
+
+## Runtime modes
+
+Agent Canvas supports several modes:
+
+| Mode | Purpose |
+|---|---|
+| `npm run dev` | Starts the full local stack directly on the host: agent-server and automation backend via `uvx`, the Vite dev server, and an ingress proxy. The agent has host filesystem access; use only in trusted environments. |
+| `npm run dev:minimal` | Starts just the agent-server plus Vite dev server, without the automation backend. |
+| `npm run dev:static` | Same as `dev`, but serves a production build of the frontend instead of the Vite dev server. |
+| `npm run dev:mock` | Runs the frontend against MSW mocks for UI development and tests. |
+| `npm run build` | Builds the standalone application. |
+| `npm run build:lib` | Builds library entrypoints for embedding Agent Canvas components. |
+
+## Packaging and distribution
+
+The npm package is `@openhands/agent-canvas`. The package exposes:
+
+- The `agent-canvas` binary for launching a local stack.
+- A standalone app build.
+- Library entrypoints for browser, conversation, files, settings, sidebar, terminal, and i18n modules.
+
+Tagged releases are published through the `Publish to npm` GitHub Actions workflow using npm trusted publishing and provenance.
+
+## Quality gates
+
+The main CI workflow installs dependencies with `npm ci` and runs:
+
+- Typecheck, ESLint, and Prettier through `npm run lint`.
+- Unit and component tests through `npm test`.
+- Standalone app build through `npm run build`.
+- Library build through `npm run build:lib`.
+- Package verification through `npm pack --dry-run`.
+
+Additional workflows run optional live end-to-end QA.
+
+## Security posture
+
+Local operation can give agents access to user workspaces. The README and self-hosting guide call out this risk and recommend Docker sandbox mode for laptop usage. Self-hosted deployments should use normal server hardening practices, authentication, HTTPS, firewall rules, and careful workspace scoping.

electron-builder.config.mjs

@@ -0,0 +1,441 @@
+/**
+ * electron-builder configuration for the Agent Canvas desktop app.
+ *
+ * `directories.app: 'electron'` tells electron-builder to use electron/package.json
+ * as the app manifest (with `"main": "main.mjs"`). This sidesteps the root
+ * package.json's `"main": "./dist/index.cjs"` without any afterPack patching.
+ *
+ * NODE_MODULES NOTE:
+ *
+ *   Even with zero `dependencies` in electron/package.json, electron-builder's
+ *   "search for node modules" routine walks UP from directories.app looking
+ *   for the first node_modules in scope. It runs `npm list --json` in the
+ *   project root, gets the full hoisted tree (~342 dirs, ~600 MB: Vite,
+ *   React, Monaco, HeroUI, etc.), and copies all of it into the packaged
+ *   app at Resources/app/node_modules/.
+ *
+ *   Almost none of those packages are imported at desktop runtime — main.mjs
+ *   and the launcher (dev-with-automation.mjs) use only Node built-ins. The
+ *   exception is the two child-process servers: static-server.mjs imports
+ *   `sirv` and ingress.mjs (via proxy-utils.mjs) imports `httpxy`. Node
+ *   resolves those bare specifiers by walking UP from the script's own path,
+ *   so an app tested from dist-electron/ inside a repo checkout accidentally
+ *   resolves them against the repo's node_modules and works — while the same
+ *   app in /Applications crashes both servers with ERR_MODULE_NOT_FOUND and
+ *   the splash times out waiting for port 8000. We can't disable the search
+ *   from the config (it's hardcoded in app-builder-lib), and creating an
+ *   empty electron/node_modules/ doesn't help because `npm list` from the
+ *   project root still reports the full hoisted tree.
+ *
+ *   The fix is the `afterPack` hook below: after electron-builder has
+ *   finished copying files, we rm -rf the bundled Resources/app/node_modules/
+ *   directory, then copy back the dependency closure of RUNTIME_PACKAGES
+ *   (~200 KB). The build wastes a few seconds copying files we immediately
+ *   delete, but the final artifact is correctly tiny (~10 MB vs ~600 MB).
+ *
+ * Packaged app layout (Resources/app/ = electron/ contents):
+ *   main.mjs        ← Electron entry point
+ *   loading.html    ← loading splash
+ *   package.json    ← {"main":"main.mjs"} (from electron/package.json)
+ *   scripts/        ← backend scripts
+ *   node_modules/   ← runtime closure of RUNTIME_PACKAGES (restored by afterPack)
+ *   config/         ← defaults.json
+ *   build/          ← static frontend (npm run build:app output)
+ *
+ * The bundled uv binary (resources/bin/) lands in <Resources>/bin/ via
+ * extraResources so Electron can inject it into PATH on startup.
+ *
+ * The bundled Node.js distribution (resources/node/) lands in
+ * <Resources>/node/ via extraResources — except for its root-level
+ * node_modules (npm itself), which electron-builder refuses to copy and the
+ * afterPack hook restores; see restoreBundledNodeNpm below.
+ *
+ * Electron prepends its bin dir to PATH at startup so backend scripts (`node
+ * scripts/ingress.mjs` etc.) and stdio MCP servers spawned via `npx -y …`
+ * (Slack, GitHub, Figma, etc.) can find a working node/npm/npx — the OS gives
+ * a Finder-launched .app a minimal PATH (/usr/bin:/bin) that has none of those.
+ */
+
+import { cp, rm } from "node:fs/promises";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// npm packages the packaged app's child-process scripts import at runtime:
+//   scripts/static-server.mjs  → sirv
+//   scripts/proxy-utils.mjs    → httpxy   (imported by ingress.mjs)
+// Their dependency closure is copied back into Resources/app/node_modules
+// after the strip below. If a spawned script gains a new bare import, add
+// the package here — a missing one crashes that service in the installed
+// app with ERR_MODULE_NOT_FOUND (invisible under Finder, where stdout goes
+// to /dev/null) and the splash times out waiting for port 8000.
+const RUNTIME_PACKAGES = ["sirv", "httpxy"];
+
+const repoRoot = dirname(fileURLToPath(import.meta.url));
+
+// Root package.json is the single source of truth for the app version
+// (release-please bumps it). electron/package.json is a minimal manifest
+// stub pinned at 1.0.0 — `extraMetadata` below overrides its version at
+// pack time so artifact names and app.getVersion() carry the released
+// version instead.
+const rootPackageJson = JSON.parse(
+  readFileSync(join(repoRoot, "package.json"), "utf8"),
+);
+
+/**
+ * Resolve the packaged app's Resources directory.
+ *
+ * On macOS it lives inside the `.app` bundle; on Linux/Windows it's a flat
+ * `resources/` subdirectory. We resolve both shapes from `context.appOutDir`
+ * + the productFilename.
+ */
+function packagedResourcesDir(context) {
+  const platform = context.electronPlatformName;
+  const productFilename = context.packager.appInfo.productFilename;
+  return platform === "darwin" || platform === "mas"
+    ? join(context.appOutDir, `${productFilename}.app`, "Contents", "Resources")
+    : join(context.appOutDir, "resources");
+}
+
+/**
+ * afterPack entry point. Invoked by electron-builder once per platform target
+ * after the unpacked directory has been populated but before installer-format
+ * packaging (DMG, NSIS, deb).
+ */
+async function afterPack(context) {
+  await stripBundledNodeModules(context);
+  await restoreBundledNodeNpm(context);
+}
+
+/**
+ * Strip the auto-bundled node_modules from the packaged app, then restore
+ * the small runtime closure of RUNTIME_PACKAGES.
+ *
+ * See the NODE_MODULES NOTE in the file header for the why.
+ */
+async function stripBundledNodeModules(context) {
+  const appDir = join(packagedResourcesDir(context), "app");
+
+  const nm = join(appDir, "node_modules");
+  if (existsSync(nm)) {
+    // Best-effort size report so the log line shows what we saved. Skip if
+    // walking the tree fails for any reason — the rm below is what matters.
+    let sizeMb = null;
+    try {
+      sizeMb = Math.round(getDirSizeBytes(nm) / (1024 * 1024));
+    } catch {}
+
+    await rm(nm, { recursive: true, force: true });
+
+    const rel = relative(process.cwd(), nm);
+    const human = sizeMb != null ? ` (~${sizeMb} MB)` : "";
+    // eslint-disable-next-line no-console -- electron-builder build log
+    console.log(
+      `[electron-builder] stripped bundled node_modules${human}: ${rel}`,
+    );
+  }
+
+  await restoreRuntimeNodeModules(appDir);
+}
+
+/**
+ * Copy the dependency closure of RUNTIME_PACKAGES from the repo's
+ * node_modules into the packaged app's Resources/app/node_modules so the
+ * spawned `node scripts/…` servers can resolve their bare imports outside
+ * a repo checkout (see RUNTIME_PACKAGES above).
+ *
+ * Resolution is deliberately simple: every package (and every transitive
+ * `dependencies` entry) is looked up at the repo root's flat npm tree, and
+ * a miss throws so the build fails loudly instead of shipping a DMG whose
+ * ingress/static-server crash on launch.
+ */
+async function restoreRuntimeNodeModules(appDir) {
+  const rootNodeModules = join(repoRoot, "node_modules");
+
+  // name → source dir, walking `dependencies` breadth-first.
+  const packages = new Map();
+  const queue = [...RUNTIME_PACKAGES];
+  while (queue.length) {
+    const name = queue.shift();
+    if (packages.has(name)) continue;
+    const srcDir = join(rootNodeModules, ...name.split("/"));
+    const manifestPath = join(srcDir, "package.json");
+    if (!existsSync(manifestPath)) {
+      throw new Error(
+        `[electron-builder] runtime package "${name}" not found in ` +
+          `${rootNodeModules} — run npm install and rebuild`,
+      );
+    }
+    packages.set(name, srcDir);
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+    queue.push(...Object.keys(manifest.dependencies ?? {}));
+  }
+
+  let totalBytes = 0;
+  for (const [name, srcDir] of packages) {
+    const destDir = join(appDir, "node_modules", ...name.split("/"));
+    await cp(srcDir, destDir, { recursive: true });
+    totalBytes += getDirSizeBytes(destDir);
+  }
+
+  // eslint-disable-next-line no-console -- electron-builder build log
+  console.log(
+    `[electron-builder] restored runtime node_modules ` +
+      `(${[...packages.keys()].join(", ")}; ~${Math.round(totalBytes / 1024)} KB)`,
+  );
+}
+
+/**
+ * Restore the bundled Node distribution's root-level `node_modules` (npm
+ * itself), which electron-builder silently refuses to copy, then verify the
+ * packed result.
+ *
+ * WHY THIS IS NEEDED — app-builder-lib's copy filter drops a `node_modules`
+ * directory sitting at the ROOT of a `from` dir, before any `filter` pattern
+ * is consulted (packages/app-builder-lib/src/util/filter.ts):
+ *
+ *     // filter the root node_modules, but not a subnode_modules
+ *     if (relative === "node_modules") {
+ *       return false
+ *     }
+ *
+ * That check is reached for extraResources too — `copyFiles()` builds the
+ * copy filter with the same `createFilter()`. Our extraResources entry copies
+ * `resources/node/` → `<Resources>/node/`, and the Windows Node zip puts npm
+ * at `<root>/node_modules/npm`, i.e. exactly `node_modules` relative to the
+ * copy root. So it is skipped, and no `filter` value can opt back in.
+ *
+ * POSIX tarballs put npm at `<root>/lib/node_modules/npm`, which is not the
+ * root entry and copies fine — which is why this only ever broke Windows and
+ * went unnoticed on macOS.
+ *
+ * Symptom when it goes wrong: `<Resources>/node/` ships a working `node.exe`
+ * next to `npm.cmd` / `npx.cmd` shims that exec
+ * `%~dp0\node_modules\npm\bin\npx-cli.js` — a file that isn't there. Every
+ * `npx -y <pkg>` spawn (stdio MCP servers, ACP servers) then dies with
+ * MODULE_NOT_FOUND, and because injectBundledNode() PREPENDS this directory
+ * to PATH it also shadows the user's own working npm installation.
+ */
+async function restoreBundledNodeNpm(context) {
+  const isWin = context.electronPlatformName === "win32";
+  const nodeDir = join(packagedResourcesDir(context), "node");
+
+  // No bundled Node at all — `npm run download-node` was skipped. That is a
+  // different (and already loudly reported) situation; main.mjs warns at
+  // startup. Don't turn it into a build failure here.
+  if (!existsSync(nodeDir)) return;
+
+  const srcNodeModules = join(repoRoot, "resources", "node", "node_modules");
+  const destNodeModules = join(nodeDir, "node_modules");
+  if (!existsSync(destNodeModules) && existsSync(srcNodeModules)) {
+    await cp(srcNodeModules, destNodeModules, { recursive: true });
+    const rel = relative(process.cwd(), destNodeModules);
+    // eslint-disable-next-line no-console -- electron-builder build log
+    console.log(
+      `[electron-builder] restored bundled Node node_modules: ${rel}`,
+    );
+  }
+
+  // Mirror the check scripts/download-node.mjs runs on the source tree, but
+  // against the packed output — the last point where a broken npm is still a
+  // build failure instead of a broken install.
+  const npmCli = isWin
+    ? join(nodeDir, "node_modules", "npm", "bin", "npm-cli.js")
+    : join(nodeDir, "lib", "node_modules", "npm", "bin", "npm-cli.js");
+  if (!existsSync(npmCli)) {
+    throw new Error(
+      `[electron-builder] packaged Node is missing npm-cli.js at ${npmCli} — ` +
+        "npm/npx would fail with MODULE_NOT_FOUND in the installed app. " +
+        "Run `npm run download-node` and rebuild.",
+    );
+  }
+}
+
+function getDirSizeBytes(dir) {
+  // Synchronous walk so we can run it before the rm without async juggling
+  // in the hook. The directory we're sizing is always small enough (<1 GB)
+  // that this is negligible compared to the rm itself.
+  let total = 0;
+  const stack = [dir];
+  while (stack.length) {
+    const next = stack.pop();
+    let entries;
+    try {
+      entries = readdirSync(next, { withFileTypes: true });
+    } catch {
+      // Best-effort: skip unreadable dirs (symlink races, permission
+      // errors on platform-specific node_modules subtrees, etc.). The
+      // size number is only used in a build-log line, so under-counting
+      // is preferable to aborting the strip.
+      continue;
+    }
+    for (const entry of entries) {
+      const p = join(next, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(p);
+      } else {
+        try {
+          total += statSync(p).size;
+        } catch {}
+      }
+    }
+  }
+  return total;
+}
+
+/** @type {import('electron-builder').Configuration} */
+const config = {
+  appId: "dev.openhands.agent-canvas",
+  productName: "OpenHands Agent Canvas",
+  copyright: "Copyright © 2025 OpenHands contributors",
+
+  // Stamp the packaged app with the released version (see rootPackageJson
+  // note above).
+  extraMetadata: { version: rootPackageJson.version },
+
+  // Treat electron/ as the app root. electron/package.json provides the
+  // Electron entry point without touching the npm-published root package.json.
+  // `buildResources` points at electron/build-resources so electron-builder
+  // can auto-discover the committed icon.icns / icon.ico (generated from the
+  // 1024×1024 icon.png master via `npm run generate-icons`) and, for Linux,
+  // icon.png itself.
+  directories: {
+    app: "electron",
+    output: "dist-electron",
+    buildResources: "electron/build-resources",
+  },
+
+  // Do not pack into asar — scripts are spawned as child processes by
+  // dev-with-automation.mjs and must exist as real files on disk.
+  asar: false,
+
+  // Skip native-module rebuild — the app has no native deps.
+  npmRebuild: false,
+
+  // Strip auto-bundled node_modules (see NODE_MODULES NOTE at top of file),
+  // then restore the bundled Node distribution's own npm (see
+  // restoreBundledNodeNpm).
+  afterPack,
+
+  // Files included in the packaged app.
+  // Paths with `from` are relative to directories.app (electron/).
+  // Bare globs are also relative to directories.app.
+  files: [
+    // electron/ base files (main.mjs, loading.html, package.json)
+    "**/*",
+    // Bundle the raw 1024×1024 PNG into Resources/app/build-resources/ so
+    // main.mjs can set it as the BrowserWindow icon at runtime (used for the
+    // Linux taskbar; macOS reads from the .icns inside the .app bundle).
+    "build-resources/icon.png",
+    // Windows runtime BrowserWindow icon (main.mjs picks .ico on win32).
+    "build-resources/icon.ico",
+    // Scripts from project root. Mostly Node built-ins; the two spawned
+    // servers additionally need RUNTIME_PACKAGES, restored into
+    // Resources/app/node_modules by the afterPack hook.
+    { from: "../scripts", to: "scripts", filter: ["**/*.mjs", "**/*.cjs"] },
+    // Centralised version / port / path config
+    { from: "../config", to: "config" },
+    // Pre-built static frontend (npm run build:app output)
+    { from: "../build", to: "build" },
+    // Custom Python tools (canvas_ui_tool.py). dev-safe.mjs sets
+    // OH_EXTRA_PYTHON_PATH to this directory so the agent-server can import
+    // canvas_ui_tool at runtime. The path is computed as ../tools relative to
+    // scripts/dev-safe.mjs, which resolves correctly in both dev and packaged mode.
+    { from: "../tools", to: "tools" },
+  ],
+
+  // Bundled prerequisites — placed in <Resources>/ so Electron can put
+  // them on PATH before starting the backend stack.
+  //   bin/   — uv + uvx (downloaded by `npm run download-uv`)
+  //   node/  — official Node.js distribution; provides `node` plus the
+  //            bundled `npm` / `npx` that stdio MCP servers (Slack, GitHub,
+  //            Figma, etc.) spawn via `npx -y <package>` (downloaded by
+  //            `npm run download-node`)
+  // `from` is relative to the project root (not directories.app).
+  // build:desktop calls both download scripts before invoking electron-builder.
+  extraResources: [
+    { from: "resources/bin/", to: "bin/", filter: ["**/*"] },
+    { from: "resources/node/", to: "node/", filter: ["**/*"] },
+  ],
+
+  // ── macOS ──────────────────────────────────────────────────────────────────
+  //
+  // Default to the native CPU arch so day-to-day `npm run build:desktop`
+  // is fast (one Electron binary, one packaging pass).
+  //
+  // For a distributable universal build set ELECTRON_ARCH=universal:
+  //   ELECTRON_ARCH=universal npm run build:desktop
+  //
+  // Or use the dedicated script:
+  //   npm run build:desktop:universal
+  //
+  // CAUTION: the bundled uv/node extraResources are downloaded for the
+  // BUILD HOST's architecture only (scripts/download-uv.mjs and
+  // download-node.mjs have no arch override), so a "universal" build still
+  // ships single-arch runtimes and breaks on the other architecture. Don't
+  // distribute universal DMGs until the download scripts support multi-arch.
+  //
+  mac: {
+    category: "public.app-category.developer-tools",
+    target: [
+      {
+        target: "dmg",
+        arch: [
+          process.env.ELECTRON_ARCH ??
+            (process.arch === "arm64" ? "arm64" : "x64"),
+        ],
+      },
+    ],
+    // Icon auto-discovered from directories.buildResources/icon.icns
+    // (committed; regenerate with `npm run generate-icons`).
+  },
+
+  dmg: {
+    title: "OpenHands Agent Canvas",
+    contents: [
+      { x: 130, y: 220 },
+      { x: 410, y: 220, type: "link", path: "/Applications" },
+    ],
+    window: { width: 540, height: 380 },
+    // Default is "OpenHands Agent Canvas-<version>-<arch>.dmg"; GitHub release
+    // assets mangle spaces, so keep the asset name literal (matches the nsis
+    // convention). ${version}/${arch}/${ext} are electron-builder macros.
+    artifactName: "OpenHands-Agent-Canvas-${version}-${arch}.${ext}",
+  },
+
+  // ── Windows ────────────────────────────────────────────────────────────────
+  win: {
+    target: [{ target: "nsis", arch: ["x64"] }],
+    // Icon auto-discovered from directories.buildResources/icon.ico
+    // (committed; regenerate with `npm run generate-icons`). Also used for
+    // the NSIS installer/uninstaller and the rcedit exe icon resource.
+  },
+
+  nsis: {
+    oneClick: false,
+    perMachine: false,
+    allowToChangeInstallationDirectory: true,
+    createDesktopShortcut: true,
+    createStartMenuShortcut: true,
+    // The default artifact name is "OpenHands Agent Canvas Setup <version>.exe";
+    // GitHub release assets mangle spaces, so ship a space-free name.
+    // ${version}/${ext} are electron-builder macros, not JS interpolation.
+    artifactName: "OpenHands-Agent-Canvas-Setup-${version}.${ext}",
+  },
+
+  // ── Linux ──────────────────────────────────────────────────────────────────
+  linux: {
+    target: [
+      { target: "AppImage", arch: ["x64"] },
+      { target: "deb", arch: ["x64"] },
+    ],
+    category: "Development",
+    // Icon auto-discovered from directories.buildResources/icon.png.
+    // fpm-backed targets (deb) require a maintainer with an email address;
+    // electron/package.json carries no author, so set it here. Without this
+    // the deb step fails with "Please specify author 'email'".
+    maintainer: "OpenHands <contact@all-hands.dev>",
+  },
+};
+
+export default config;

eslint.config.js

@@ -0,0 +1,392 @@
+// Flat ESLint config (ESLint 9+).
+//
+// Migration notes (see commit history for full context):
+// - Replaces the legacy `.eslintrc` file, which ESLint 9 deprecated and
+//   ESLint 10 will remove entirely.
+// - Drops `eslint-config-airbnb` / `eslint-config-airbnb-typescript`: they
+//   pin ESLint to v7/v8 and `@typescript-eslint/*` to v7, so they block any
+//   future ESLint major bumps. The opinionated airbnb rules the codebase
+//   actually leaned on (no-param-reassign, import/extensions, etc.) are
+//   re-declared explicitly below, and the long list of airbnb rules the old
+//   config already turned off has just been deleted instead of re-disabled.
+// - Replaces `eslint-plugin-import` (only declares an `^8 || ^9` peer) with
+//   the actively-maintained, flat-config-native fork `eslint-plugin-import-x`.
+//   The rule names are kept under the `import/` prefix below to minimise
+//   churn on existing `// eslint-disable-next-line import/...` comments.
+// - `eslint-plugin-i18next` still ships only legacy config, so it is pulled
+//   in via `FlatCompat` from `@eslint/eslintrc`.
+// - Targets ESLint 9, not 10. The original dependabot PR proposed eslint@10,
+//   but as of this commit `eslint-plugin-react` still calls
+//   `context.getFilename()` (removed in ESLint 10) at rule-load time, which
+//   makes a v10 bump explode on every file. Re-evaluate once that plugin
+//   ships an ESLint-10-compatible release.
+
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+import { FlatCompat } from "@eslint/eslintrc";
+import js from "@eslint/js";
+import tsParser from "@typescript-eslint/parser";
+import tsPlugin from "@typescript-eslint/eslint-plugin";
+import reactPlugin from "eslint-plugin-react";
+import reactHooksPlugin from "eslint-plugin-react-hooks";
+import jsxA11yPlugin from "eslint-plugin-jsx-a11y";
+import importXPlugin from "eslint-plugin-import-x";
+import prettierPlugin from "eslint-plugin-prettier";
+import prettierConfig from "eslint-config-prettier";
+import unusedImportsPlugin from "eslint-plugin-unused-imports";
+import tanstackQueryPlugin from "@tanstack/eslint-plugin-query";
+import globals from "globals";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+  resolvePluginsRelativeTo: __dirname,
+});
+
+/**
+ * ESLint rule: forbid raw `fetch` calls that target an agent-server `/api/...`
+ * path, so API access goes through the typed @openhands/typescript-client
+ * clients. Only statically-resolvable agent-server paths are flagged; external
+ * URLs, dynamic identifiers, and non-`/api/` draws (cookie-auth static
+ * fileserver, OAuth device verification) are left alone.
+ */
+function createNoDirectAgentServerFetchRule() {
+  return {
+    meta: {
+      type: "problem",
+      docs: {
+        description:
+          "Use typed @openhands/typescript-client clients instead of global fetch for agent-server API calls.",
+      },
+      messages: {
+        noRawFetch:
+          "Use a typed @openhands/typescript-client client (or AgentServerClient.request) instead of global fetch for agent-server API calls.",
+      },
+    },
+    create(context) {
+      function resolveStaticUrl(node) {
+        if (node.type === "Literal" && typeof node.value === "string") {
+          return node.value;
+        }
+        if (node.type === "TemplateLiteral") {
+          return node.quasis
+            .map((q) => q.value.raw)
+            .join("");
+        }
+        return null;
+      }
+
+      return {
+        CallExpression(node) {
+          const callee = node.callee;
+          if (callee.type !== "Identifier" || callee.name !== "fetch") return;
+          const urlNode = node.arguments[0];
+          if (!urlNode) return;
+          const url = resolveStaticUrl(urlNode);
+          if (url === null || !url.includes("/api/")) return;
+          context.report({ node, messageId: "noRawFetch" });
+        },
+      };
+    },
+  };
+}
+
+export default [
+  // Files / dirs we never want to lint.
+  {
+    ignores: [
+      "node_modules/**",
+      "dist/**",
+      "build/**",
+      "coverage/**",
+      ".react-router/**",
+      "playwright-report/**",
+      "playwright-report-live/**",
+      "test-results/**",
+      "test-results-live/**",
+      "public/mockServiceWorker.js",
+      // Self-contained browser ES module served to extensions at runtime;
+      // not part of the TypeScript project.
+      "src/fixtures/canvas-extensions/**/*.js",
+      "src/i18n/declaration.d.ts",
+    ],
+  },
+
+  // Base JS recommended rules.
+  js.configs.recommended,
+
+  // `eslint-plugin-import-x` ships flat configs directly. The rules are
+  // registered under both `import-x/*` and `import/*` aliases so existing
+  // `// eslint-disable-next-line import/*` comments still match.
+  importXPlugin.flatConfigs.recommended,
+  importXPlugin.flatConfigs.typescript,
+
+  // `eslint-plugin-i18next` is still eslintrc-only — pull it in via compat.
+  ...compat.extends("plugin:i18next/recommended"),
+
+  // Project-wide settings + React/TS/etc. rules for source files.
+  {
+    files: ["**/*.{ts,tsx,js,jsx,mjs,cjs}"],
+    // Surface (but don't fail on) `// eslint-disable-next-line ...` directives
+    // that target rules this config no longer enables. The codebase has ~50
+    // such directives left over from the airbnb era; "warn" lets us clean
+    // them up incrementally instead of either failing CI on day one or
+    // letting new stale directives accumulate silently.
+    linterOptions: {
+      reportUnusedDisableDirectives: "warn",
+    },
+    languageOptions: {
+      ecmaVersion: "latest",
+      sourceType: "module",
+      parser: tsParser,
+      parserOptions: {
+        project: "./tsconfig.json",
+        ecmaFeatures: { jsx: true },
+      },
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+        ...globals.es2024,
+      },
+    },
+    plugins: {
+      "@typescript-eslint": tsPlugin,
+      react: reactPlugin,
+      "react-hooks": reactHooksPlugin,
+      "jsx-a11y": jsxA11yPlugin,
+      "@tanstack/query": tanstackQueryPlugin,
+      "unused-imports": unusedImportsPlugin,
+      // Alias `import-x` rules under `import/*` so existing
+      // `// eslint-disable-next-line import/foo` comments keep working.
+      import: importXPlugin,
+      prettier: prettierPlugin,
+      // Local rule enforcing that agent-server API calls go through the typed
+      // @openhands/typescript-client clients instead of a raw `fetch`.
+      local: {
+        rules: {
+          "no-direct-agent-server-fetch":
+            createNoDirectAgentServerFetchRule(),
+        },
+      },
+    },
+    settings: {
+      react: { version: "detect" },
+      // `eslint-import-resolver-typescript` resolves both TS path aliases
+      // (via tsconfig) and regular node-style imports, so we don't also
+      // configure the legacy `node` resolver shortcut here.
+      "import-x/resolver": {
+        typescript: true,
+      },
+    },
+    rules: {
+      // Recommended rule packs we want everywhere.
+      ...tsPlugin.configs["eslint-recommended"].overrides[0].rules,
+      ...tsPlugin.configs.recommended.rules,
+      ...reactPlugin.configs.recommended.rules,
+      ...reactPlugin.configs["jsx-runtime"].rules,
+      ...reactHooksPlugin.configs.recommended.rules,
+      ...jsxA11yPlugin.configs.recommended.rules,
+      ...tanstackQueryPlugin.configs.recommended.rules,
+
+      // Prettier integration. `eslint-config-prettier` turns off conflicting
+      // stylistic rules; `eslint-plugin-prettier` re-reports prettier diffs
+      // as lint errors so `npm run lint` fails on unformatted code (matching
+      // the pre-flat-config behaviour).
+      ...prettierConfig.rules,
+      "prettier/prettier": "error",
+
+      // Project conventions previously enforced via airbnb / custom rules.
+      // Lint JSX *attributes* (not just text between tags) for hard-coded
+      // user-facing strings. The plugin default (`mode: 'jsx-text-only'`)
+      // never checks attribute values, which let untranslated strings like
+      // `aria-label="Close"` / `placeholder="..."` slip past lint (cf. #1306).
+      //
+      // `jsx-only` checks every literal inside a JSX subtree, so we scope it:
+      //  - jsx-attributes.include: only attributes that carry translatable
+      //    text. Everything else (testId, name, color, to, href, className,
+      //    data-*, …) is ignored automatically — no brittle deny-list.
+      //  - callees/object-properties: re-list the plugin defaults (the option
+      //    merge is shallow, so providing a key replaces it) and add
+      //    `cn`/`className` so Tailwind class strings built via `cn(...)` or
+      //    `{ className: "..." }` aren't flagged.
+      "i18next/no-literal-string": [
+        "error",
+        {
+          mode: "jsx-only",
+          "jsx-attributes": {
+            include: [
+              "placeholder",
+              "alt",
+              "aria-label",
+              "title",
+              "label",
+              "heading",
+              "text",
+            ],
+          },
+          callees: {
+            exclude: [
+              "i18n(ext)?",
+              "t",
+              "require",
+              "addEventListener",
+              "removeEventListener",
+              "postMessage",
+              "getElementById",
+              "dispatch",
+              "commit",
+              "includes",
+              "indexOf",
+              "endsWith",
+              "startsWith",
+              "cn",
+            ],
+          },
+          "object-properties": {
+            exclude: ["[A-Z_-]+", "className"],
+          },
+        },
+      ],
+      "unused-imports/no-unused-imports": "error",
+      "@typescript-eslint/prefer-optional-chain": "error",
+      "no-restricted-imports": [
+        "error",
+        {
+          paths: [
+            {
+              name: "@openhands/typescript-client/client/http-client",
+              message:
+                "Use typed @openhands/typescript-client clients instead of constructing HttpClient directly.",
+            },
+          ],
+        },
+      ],
+      // All agent-server API access must go through the typed
+      // @openhands/typescript-client clients. A raw global `fetch` against an
+      // agent-server `/api/...` path bypasses the typed access layer, so it is
+      // banned here (see also src/api/no-direct-agent-server-calls.test.ts).
+      // Browser-cookie-auth and external (non-agent-server) fetches — e.g. the
+      // workspace static fileserver, OAuth device verification, and the npm
+      // registry version check — do not target `/api/...` and are unaffected.
+      "local/no-direct-agent-server-fetch": "error",
+
+      // Allow `interface Foo extends Bar<"foo"> {}` — the codebase uses this
+      // discriminated-union pattern in `src/types/agent-server/**` and the
+      // empty body is intentional. We still disallow `interface Foo {}` and
+      // `type Foo = {}` (the default behaviour for the other two options).
+      "@typescript-eslint/no-empty-object-type": [
+        "error",
+        { allowInterfaces: "with-single-extends" },
+      ],
+
+      // tsPlugin's `recommended` enables no-unused-vars; we already report
+      // unused imports above, so make sure the TS rule still catches unused
+      // locals/args (with the standard airbnb-style `_`-prefix escape hatch).
+      // `caughtErrors: 'none'` keeps the v7 behaviour of allowing
+      // `catch (error)` clauses where the error is intentionally unused.
+      "no-unused-vars": "off",
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        {
+          args: "after-used",
+          argsIgnorePattern: "^_",
+          varsIgnorePattern: "^_",
+          ignoreRestSiblings: true,
+          caughtErrors: "none",
+        },
+      ],
+
+      // React Compiler rules (added in eslint-plugin-react-hooks v5+) are
+      // opt-in for projects that have actually adopted the compiler. Keep
+      // them off so existing code isn't retroactively flagged.
+      "react-hooks/immutability": "off",
+      "react-hooks/preserve-manual-memoization": "off",
+      "react-hooks/refs": "off",
+      "react-hooks/set-state-in-effect": "off",
+
+      // Match the legacy config: don't require .ts/.tsx import extensions,
+      // but enforce them for everything else. See
+      // https://stackoverflow.com/q/59265981 for background.
+      "import-x/extensions": [
+        "error",
+        "ignorePackages",
+        { "": "never", ts: "never", tsx: "never", js: "never", jsx: "never" },
+      ],
+      // The old config inherited a bunch of import rules from airbnb that
+      // either don't apply or are now noise; explicitly turn off the ones
+      // most likely to fire on this codebase.
+      "import-x/prefer-default-export": "off",
+      "import-x/no-extraneous-dependencies": "off",
+      // `import-x/no-unresolved` is redundant with the TypeScript compiler:
+      // `tsc` (run as `npm run typecheck` before `eslint`) already fails on
+      // unresolved imports with much better error messages, and the rule
+      // has known false positives with `paths`/exports-map resolution even
+      // when the typescript resolver is configured. Keeping it on duplicates
+      // tsc errors and produces noise on Vite's `?url` / `?worker` import
+      // suffixes that ESLint can't see through.
+      "import-x/no-unresolved": "off",
+      // These two fire a lot of false positives on TypeScript projects that
+      // import a namespace and then call methods off it (`import api from
+      // './foo'; api.bar()` etc.). The TS compiler already catches anything
+      // truly wrong here.
+      "import-x/no-named-as-default": "off",
+      "import-x/no-named-as-default-member": "off",
+    },
+  },
+
+  // TypeScript-only overrides (re-applied airbnb-ish relaxations from the
+  // previous `.eslintrc` overrides block).
+  {
+    files: ["**/*.{ts,tsx}"],
+    ignores: ["src/hooks/query/query-keys.ts"],
+    rules: {
+      // Allow state mutation in reduce and Redux-style reducers.
+      "no-param-reassign": [
+        "error",
+        {
+          props: true,
+          ignorePropertyModificationsFor: ["acc", "state"],
+        },
+      ],
+      "no-restricted-syntax": [
+        "error",
+        {
+          selector:
+            "Property[key.name='queryKey'] > ArrayExpression[elements.0.value='settings']",
+          message:
+            "Use SETTINGS_QUERY_KEYS helpers instead of raw settings query key arrays.",
+        },
+        {
+          selector:
+            "CallExpression[callee.name='t'] > Literal:first-child[value=/^[A-Z0-9_]+\\$/]",
+          message: "Use I18nKey instead of raw translation key strings.",
+        },
+        {
+          selector:
+            "CallExpression[callee.property.name='t'] > Literal:first-child[value=/^[A-Z0-9_]+\\$/]",
+          message: "Use I18nKey instead of raw translation key strings.",
+        },
+      ],
+      "react/require-default-props": "off",
+      "no-underscore-dangle": "off",
+      "jsx-a11y/no-static-element-interactions": "off",
+      "jsx-a11y/click-events-have-key-events": "off",
+      // For https://github.com/airbnb/javascript/issues/1885
+      "jsx-a11y/label-has-associated-control": [
+        2,
+        {
+          required: {
+            some: ["nesting", "id"],
+          },
+        },
+      ],
+      "react/prop-types": "off",
+      "react/no-array-index-key": "off",
+      "react-hooks/exhaustive-deps": "off",
+      "react/react-in-jsx-scope": "off",
+    },
+  },
+];

global.d.ts

@@ -0,0 +1,18 @@
+interface Window {
+  __GITHUB_CLIENT_ID__?: string | null;
+}
+
+declare module "postcss-prefix-selector" {
+  interface PrefixerOptions {
+    prefix: string;
+    transform?: (
+      prefix: string,
+      selector: string,
+      prefixedSelector: string,
+    ) => string;
+  }
+
+  export default function prefixer(
+    options: PrefixerOptions,
+  ): import("postcss").AcceptedPlugin;
+}

hero.ts

@@ -0,0 +1,65 @@
+import { heroui } from "@heroui/react";
+
+export default heroui({
+  defaultTheme: "dark",
+  layout: {
+    radius: {
+      small: "5px",
+      large: "20px",
+    },
+  },
+  themes: {
+    dark: {
+      colors: {
+        primary: "#4465DB",
+
+        // Map HeroUI's zinc-based semantic colours to our cool-grey palette.
+        // This ensures every HeroUI component that uses bg-default, bg-content*,
+        // etc. stays within the same colour family as the rest of the UI.
+
+        background: {
+          DEFAULT: "#0B0E14", // cool-grey-950 — app shell base
+          foreground: "#F7F9FC", // cool-grey-50
+        },
+
+        foreground: {
+          DEFAULT: "#C3CDDC", // cool-grey-300 — primary readable text
+          "50": "#05070A", // cool-grey-975
+          "100": "#0B0E14", // cool-grey-950
+          "200": "#21252F", // cool-grey-925
+          "300": "#2C313F", // cool-grey-900
+          "400": "#383F50", // cool-grey-800
+          "500": "#4B5468", // cool-grey-700
+          "600": "#626D82", // cool-grey-600
+          "700": "#7E8A9E", // cool-grey-500
+          "800": "#A3B0C4", // cool-grey-400
+          "900": "#C3CDDC", // cool-grey-300
+        },
+
+        // Surface layers: panel → card → inner card → inset
+        content1: { DEFAULT: "#21252F", foreground: "#EEF2F7" }, // cool-grey-925 / 100
+        content2: { DEFAULT: "#2C313F", foreground: "#DCE3EE" }, // cool-grey-900 / 200
+        content3: { DEFAULT: "#383F50", foreground: "#C3CDDC" }, // cool-grey-800 / 300
+        content4: { DEFAULT: "#4B5468", foreground: "#A3B0C4" }, // cool-grey-700 / 400
+
+        focus: {
+          DEFAULT: "#ffffff", // white focus ring — visible on all dark surfaces
+        },
+        default: {
+          "50": "#05070A", // cool-grey-975
+          "100": "#0B0E14", // cool-grey-950
+          "200": "#21252F", // cool-grey-925
+          "300": "#2C313F", // cool-grey-900
+          "400": "#383F50", // cool-grey-800
+          "500": "#4B5468", // cool-grey-700
+          "600": "#626D82", // cool-grey-600
+          "700": "#7E8A9E", // cool-grey-500
+          "800": "#A3B0C4", // cool-grey-400
+          "900": "#C3CDDC", // cool-grey-300
+          DEFAULT: "#383F50", // cool-grey-800 — hover/selected tint
+          foreground: "#F7F9FC", // cool-grey-50 — text on default bg
+        },
+      },
+    },
+  },
+});

package.json

@@ -0,0 +1,254 @@
+{
+  "name": "@openhands/agent-canvas",
+  "version": "1.18.0",
+  "description": "Agent Canvas UI for OpenHands - run AI coding agents with a visual interface",
+  "license": "MIT",
+  "private": false,
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/OpenHands/OpenHands"
+  },
+  "homepage": "https://github.com/OpenHands/OpenHands#readme",
+  "bugs": {
+    "url": "https://github.com/OpenHands/OpenHands/issues"
+  },
+  "bin": {
+    "agent-canvas": "bin/agent-canvas.mjs"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "dependencies": {
+    "@heroui/react": "2.8.10",
+    "@microlink/react-json-view": "1.31.25",
+    "@monaco-editor/react": "4.7.0",
+    "@openhands/extensions": "0.20.0",
+    "@openhands/typescript-client": "1.46.0",
+    "@react-router/node": "7.18.2",
+    "@react-router/serve": "7.18.2",
+    "@tailwindcss/vite": "4.3.3",
+    "@tanstack/react-query": "5.101.4",
+    "@types/shell-quote": "1.7.5",
+    "@uidotdev/usehooks": "2.4.1",
+    "@xterm/addon-fit": "0.11.0",
+    "@xterm/xterm": "6.0.0",
+    "axios": "1.18.0",
+    "class-variance-authority": "0.7.1",
+    "clsx": "2.1.1",
+    "downshift": "9.3.2",
+    "framer-motion": "12.38.0",
+    "httpxy": "0.5.3",
+    "i18next": "26.3.6",
+    "i18next-browser-languagedetector": "8.2.1",
+    "i18next-http-backend": "4.0.1",
+    "isbot": "5.1.39",
+    "lucide-react": "1.25.0",
+    "monaco-editor": "0.56.0",
+    "posthog-js": "1.380.0",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "react-hot-toast": "2.6.0",
+    "react-i18next": "17.0.11",
+    "react-icons": "5.6.0",
+    "react-markdown": "10.1.0",
+    "react-router": "7.18.2",
+    "react-syntax-highlighter": "16.1.1",
+    "rehype-raw": "7.0.0",
+    "rehype-sanitize": "6.0.0",
+    "remark-breaks": "4.0.0",
+    "remark-gfm": "4.0.1",
+    "shell-quote": "1.9.0",
+    "sirv": "3.0.2",
+    "sirv-cli": "3.0.1",
+    "socket.io-client": "4.8.3",
+    "tailwind-merge": "3.6.0",
+    "tailwind-scrollbar": "4.0.2",
+    "unist-util-visit": "5.1.0",
+    "uuid": "14.0.0",
+    "vite": "8.0.16",
+    "winston": "3.19.0",
+    "winston-daily-rotate-file": "5.0.0",
+    "zustand": "5.0.14"
+  },
+  "scripts": {
+    "dev": "node --env-file-if-exists=.env scripts/dev-with-automation.mjs",
+    "dev:static": "node --env-file-if-exists=.env scripts/dev-static.mjs",
+    "dev:extra-backend": "node --env-file-if-exists=.env scripts/dev-extra-backend.mjs",
+    "dev:minimal": "node --env-file-if-exists=.env scripts/dev-safe.mjs",
+    "dev:frontend": "npm run make-i18n && cross-env VITE_MOCK_API=false react-router dev",
+    "dev:mock": "npm run make-i18n && cross-env VITE_MOCK_API=true react-router dev",
+    "build": "npm run build:app",
+    "build:mock": "npm run make-i18n && cross-env VITE_MOCK_API=true react-router build",
+    "start": "npx sirv-cli build/ --single",
+    "test": "npm run make-i18n && vitest run",
+    "test:e2e": "playwright test --pass-with-no-tests",
+    "test:e2e:live": "node --env-file-if-exists=.env tests/e2e/live/scripts/run-live-e2e.mjs",
+    "test:e2e:mock-llm": "playwright test --config=playwright.mock-llm.config.ts",
+    "test:e2e:mock-llm:docker": "playwright test --config=playwright.mock-llm-docker.config.ts",
+    "test:coverage": "npm run make-i18n && vitest run --coverage",
+    "test:mutation": "npm run make-i18n && stryker run",
+    "test:mutation:diff": "npm run make-i18n && node scripts/stryker-diff.mjs",
+    "test:mutation:incremental": "npm run make-i18n && stryker run --incremental",
+    "dev_wsl": "VITE_WATCH_USE_POLLING=true vite",
+    "preview": "vite preview",
+    "make-i18n": "node scripts/make-i18n-translations.cjs",
+    "prelint": "npm run make-i18n",
+    "lint": "npm run typecheck && eslint src && prettier --check src/**/*.{ts,tsx}",
+    "lint:fix": "eslint src --fix && prettier --write src/**/*.{ts,tsx}",
+    "postinstall": "node -e \"if (process.env.npm_config_global === 'true') { console.log('\\n\\x1b[32m\\x1b[1m\\u2713 @openhands/agent-canvas installed!\\x1b[0m\\n\\nTo start Agent Canvas, run:\\n\\n  \\x1b[36m\\x1b[1magent-canvas\\x1b[0m\\n\\nThis launches the full stack at \\x1b[36mhttp://localhost:8000\\x1b[0m.\\n\\nDocs: https://docs.openhands.dev/openhands/usage/agent-canvas/setup\\n') }\"",
+    "prepare": "husky",
+    "typecheck": "react-router typegen && tsc",
+    "typecheck:staged": "react-router typegen && npx tsc --noEmit --skipLibCheck",
+    "check-translation-completeness": "node scripts/check-translation-completeness.cjs",
+    "build:app": "npm run make-i18n && react-router build",
+    "build:lib": "npm run make-i18n && react-router typegen && cross-env BUILD_LIB=true vite build && tsc -p tsconfig.lib.json",
+    "build:docker": "node scripts/docker-build.mjs",
+    "example:acp-docker:env": "node scripts/gen-acp-docker-env.mjs",
+    "predesktop": "node scripts/brand-dev-electron.mjs",
+    "desktop": "npm run build:app && electron electron",
+    "build:desktop": "npm run build:app && node scripts/download-uv.mjs && node scripts/download-node.mjs && electron-builder --config electron-builder.config.mjs --publish never",
+    "build:desktop:universal": "npm run build:app && node scripts/download-uv.mjs && node scripts/download-node.mjs && cross-env ELECTRON_ARCH=universal electron-builder --config electron-builder.config.mjs --publish never",
+    "download-uv": "node scripts/download-uv.mjs",
+    "download-node": "node scripts/download-node.mjs",
+    "generate-icons": "node scripts/generate-icons.mjs"
+  },
+  "lint-staged": {
+    "src/**/*.{ts,tsx,js}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "src/**/*.{ts,tsx}": [
+      "node scripts/run-staged-typecheck.mjs"
+    ],
+    "src/**/*": [
+      "npm run check-translation-completeness"
+    ]
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "3.3.6",
+    "@eslint/js": "9.39.4",
+    "@mswjs/socket.io-binding": "0.2.0",
+    "@playwright/test": "1.62.1",
+    "@react-router/dev": "7.18.2",
+    "@stryker-mutator/core": "9.6.1",
+    "@stryker-mutator/vitest-runner": "9.6.1",
+    "@tailwindcss/typography": "0.5.20",
+    "@tanstack/eslint-plugin-query": "5.101.4",
+    "@testing-library/dom": "10.4.1",
+    "@testing-library/jest-dom": "7.0.0",
+    "@testing-library/react": "16.3.2",
+    "@testing-library/user-event": "14.6.1",
+    "@types/mdast": "4.0.4",
+    "@types/node": "26.1.2",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.4",
+    "@types/react-syntax-highlighter": "15.5.13",
+    "@typescript-eslint/eslint-plugin": "8.65.0",
+    "@typescript-eslint/parser": "8.65.0",
+    "@vercel/react-router": "1.3.0",
+    "@vitest/coverage-v8": "4.1.10",
+    "cross-env": "10.1.0",
+    "electron": "42.3.3",
+    "electron-builder": "26.15.3",
+    "eslint": "9.39.5",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-import-resolver-typescript": "4.4.5",
+    "eslint-plugin-i18next": "6.1.5",
+    "eslint-plugin-import-x": "4.17.1",
+    "eslint-plugin-jsx-a11y": "6.10.2",
+    "eslint-plugin-prettier": "5.5.6",
+    "eslint-plugin-react": "7.37.5",
+    "eslint-plugin-react-hooks": "7.1.1",
+    "eslint-plugin-unused-imports": "4.4.1",
+    "globals": "16.5.0",
+    "husky": "9.1.7",
+    "jsdom": "30.0.1",
+    "lint-staged": "17.3.0",
+    "msw": "2.15.0",
+    "png2icons": "2.0.1",
+    "postcss-prefix-selector": "2.1.1",
+    "prettier": "3.8.3",
+    "tailwindcss": "4.3.3",
+    "typescript": "6.0.3",
+    "vite-plugin-svgr": "5.2.0",
+    "vitest": "4.1.10"
+  },
+  "packageManager": "npm@10.5.0",
+  "volta": {
+    "node": "22.12.0"
+  },
+  "msw": {
+    "workerDirectory": [
+      "public"
+    ]
+  },
+  "overrides": {
+    "@vercel/static-config": {
+      "ajv": "8.20.0"
+    },
+    "dompurify": "3.4.14",
+    "typed-rest-client": {
+      "qs": "6.15.3"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "bin",
+    "build",
+    "config",
+    "scripts",
+    "tools"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./browser": {
+      "types": "./dist/components/browser/index.d.ts",
+      "import": "./dist/components/browser/index.js",
+      "require": "./dist/components/browser/index.cjs"
+    },
+    "./conversation": {
+      "types": "./dist/components/conversation/index.d.ts",
+      "import": "./dist/components/conversation/index.js",
+      "require": "./dist/components/conversation/index.cjs"
+    },
+    "./files": {
+      "types": "./dist/components/files/index.d.ts",
+      "import": "./dist/components/files/index.js",
+      "require": "./dist/components/files/index.cjs"
+    },
+    "./settings": {
+      "types": "./dist/components/settings/index.d.ts",
+      "import": "./dist/components/settings/index.js",
+      "require": "./dist/components/settings/index.cjs"
+    },
+    "./sidebar": {
+      "types": "./dist/components/sidebar/index.d.ts",
+      "import": "./dist/components/sidebar/index.js",
+      "require": "./dist/components/sidebar/index.cjs"
+    },
+    "./terminal": {
+      "types": "./dist/components/terminal/index.d.ts",
+      "import": "./dist/components/terminal/index.js",
+      "require": "./dist/components/terminal/index.cjs"
+    },
+    "./i18n": {
+      "types": "./dist/i18n/index.d.ts",
+      "import": "./dist/i18n/index.js",
+      "require": "./dist/i18n/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "react-router": "7.18.2"
+  }
+}

playwright.config.ts

@@ -0,0 +1,85 @@
+import { defineConfig, devices } from "@playwright/test";
+
+/**
+ * Read environment variables from file.
+ * https://github.com/motdotla/dotenv
+ */
+// import dotenv from 'dotenv';
+// import path from 'path';
+// dotenv.config({ path: path.resolve(__dirname, '.env') });
+
+/**
+ * See https://playwright.dev/docs/test-configuration.
+ */
+export default defineConfig({
+  testDir: "./tests/e2e",
+  testIgnore: ["**/e2e/live/**", "**/e2e/mock-llm/**"],
+  /* Run tests in files in parallel */
+  fullyParallel: true,
+  /* Fail the build on CI if you accidentally left test.only in the source code. */
+  forbidOnly: !!process.env.CI,
+  /* Retry on CI only */
+  retries: process.env.CI ? 2 : 0,
+  /* Use 2 workers on CI (matches ubuntu-24.04's 2 vCPUs). Tests are isolated
+   * per browser context so parallel execution is safe. */
+  workers: process.env.CI ? 2 : undefined,
+  /* Reporter to use. See https://playwright.dev/docs/test-reporters */
+  reporter: "html",
+
+  /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
+  use: {
+    /* Base URL to use in actions like `await page.goto('/')`. */
+    baseURL: "http://localhost:3001/",
+
+    /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
+    trace: "on-first-retry",
+    /* Ignore SSL errors for browser agent test */
+    /* Solution inspired by StackOverflow post: https://stackoverflow.com/questions/67048422/ignore-ssl-errors-with-playwright-code-generation */
+    ignoreHTTPSErrors: true,
+  },
+
+  /* Configure projects for major browsers */
+  projects: [
+    {
+      name: "chromium",
+      use: { ...devices["Desktop Chrome"] },
+    },
+
+    {
+      name: "firefox",
+      use: { ...devices["Desktop Firefox"] },
+    },
+
+    {
+      name: "webkit",
+      use: { ...devices["Desktop Safari"] },
+    },
+
+    /* Test against mobile viewports. */
+    // {
+    //   name: 'Mobile Chrome',
+    //   use: { ...devices['Pixel 5'] },
+    // },
+    // {
+    //   name: 'Mobile Safari',
+    //   use: { ...devices['iPhone 12'] },
+    // },
+
+    /* Test against branded browsers. */
+    // {
+    //   name: 'Microsoft Edge',
+    //   use: { ...devices['Desktop Edge'], channel: 'msedge' },
+    // },
+    // {
+    //   name: 'Google Chrome',
+    //   use: { ...devices['Desktop Chrome'], channel: 'chrome' },
+    // },
+  ],
+
+  /* Run your local dev server before starting the tests */
+  webServer: {
+    command: "npm run dev:mock -- --port 3001",
+    url: "http://localhost:3001/",
+    reuseExistingServer: !process.env.CI,
+  },
+});

playwright.live.config.ts

@@ -0,0 +1,74 @@
+import { defineConfig, devices } from "@playwright/test";
+import { randomBytes } from "node:crypto";
+
+const configuredLiveE2ESessionApiKey =
+  process.env.LIVE_E2E_SESSION_API_KEY?.trim();
+const liveE2ESessionApiKey =
+  configuredLiveE2ESessionApiKey || randomBytes(32).toString("hex");
+process.env.LIVE_E2E_SESSION_API_KEY = liveE2ESessionApiKey;
+const liveE2EFrontendPort = process.env.LIVE_E2E_FRONTEND_PORT ?? "3101";
+const liveE2EBackendURL =
+  process.env.LIVE_E2E_BACKEND_URL ?? "http://127.0.0.1:18100";
+let liveE2EBackendPort: string;
+try {
+  liveE2EBackendPort = new URL(liveE2EBackendURL).port || "18100";
+} catch {
+  throw new Error("Invalid LIVE_E2E_BACKEND_URL. Expected an absolute URL.");
+}
+const liveE2EFrontendURL = `http://localhost:${liveE2EFrontendPort}/`;
+const liveE2EVideoMode =
+  process.env.LIVE_E2E_RECORD_VIDEO === "on" ? "on" : "retain-on-failure";
+
+function shellQuote(value: string) {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function envAssignment(name: string, value: string) {
+  return `${name}=${shellQuote(value)}`;
+}
+
+export default defineConfig({
+  testDir: "./tests/e2e/live",
+  testMatch: /.*\.spec\.ts/,
+  fullyParallel: false,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 1 : 0,
+  workers: 1,
+  timeout: 180_000,
+  reporter: [
+    ["line"],
+    ["json", { outputFile: "test-results-live/results.json" }],
+    ["html", { outputFolder: "playwright-report-live", open: "never" }],
+  ],
+  outputDir: "test-results-live",
+  use: {
+    baseURL: liveE2EFrontendURL,
+    screenshot: "only-on-failure",
+    trace: "off",
+    video: liveE2EVideoMode,
+  },
+  projects: [
+    {
+      name: "chromium",
+      use: { ...devices["Desktop Chrome"] },
+    },
+  ],
+  // This live stack is intended for macOS/Linux shells and Ubuntu CI runners;
+  // the command below intentionally uses POSIX environment assignment syntax.
+  webServer: {
+    command:
+      "node -e \"const fs=require('node:fs'); for (const p of ['.tmp/live-e2e-state','node_modules/.vite']) fs.rmSync(p,{recursive:true,force:true});\" && " +
+      [
+        "OH_CANVAS_SAFE_STATE_DIR=.tmp/live-e2e-state",
+        envAssignment("LOCAL_BACKEND_API_KEY", liveE2ESessionApiKey),
+        envAssignment("OH_CANVAS_SAFE_BACKEND_PORT", liveE2EBackendPort),
+        "VITE_DO_NOT_TRACK=1",
+        "VITE_ENABLE_BROWSER_TOOLS=false",
+        envAssignment("VITE_FRONTEND_PORT", liveE2EFrontendPort),
+        "npm run dev:minimal",
+      ].join(" "),
+    url: liveE2EFrontendURL,
+    timeout: 120_000,
+    reuseExistingServer: false,
+  },
+});

playwright.mock-llm-docker.config.ts

@@ -0,0 +1,239 @@
+/**
+ * Playwright config for mock-LLM E2E tests against a Docker container.
+ *
+ * Reuses the same test specs as playwright.mock-llm.config.ts but launches
+ * the agent-canvas stack inside a Docker container instead of via
+ * bin/agent-canvas.mjs + uvx.
+ *
+ * Starts two processes:
+ *   1. Mock LLM server (Python on the host, using openhands-sdk TestLLM)
+ *   2. Docker container running the agent-canvas all-in-one image
+ *      (agent-server + automation backend + static frontend + proxy)
+ *      The container also starts a second static-server instance on
+ *      PUBLIC_MODE_PORT with --auth-required for auth-mode E2E tests.
+ *
+ * Networking:
+ *   Uses --network host on Linux so the container shares the host's network
+ *   stack. This means the agent-server inside Docker can reach the mock LLM
+ *   server at 127.0.0.1:<port> — identical to the npm path.
+ *
+ *   For macOS/Windows (Docker Desktop with bridge networking), set
+ *   MOCK_LLM_AGENT_URL=http://host.docker.internal:<port> so the
+ *   agent-server can reach the host-side mock LLM server.
+ *
+ * Required:
+ *   - A built Docker image. Set MOCK_LLM_DOCKER_IMAGE to the image tag
+ *     (default: ghcr.io/openhands/agent-canvas:latest).
+ *   - Docker daemon must be running.
+ */
+
+import { defineConfig, devices } from "@playwright/test";
+import { randomBytes } from "node:crypto";
+import { mkdirSync } from "node:fs";
+import { resolve } from "node:path";
+
+// ── Docker image ────────────────────────────────────────────────────────
+const DOCKER_IMAGE =
+  process.env.MOCK_LLM_DOCKER_IMAGE ?? "ghcr.io/openhands/agent-canvas:latest";
+
+// Container name for cleanup — unique per run to avoid collisions.
+const CONTAINER_NAME =
+  process.env.MOCK_LLM_CONTAINER_NAME ??
+  `agent-canvas-mock-llm-${randomBytes(4).toString("hex")}`;
+
+// ── Port allocation (separate from live E2E / dev to avoid collisions) ─
+const MOCK_LLM_PORT = process.env.MOCK_LLM_PORT ?? "9999";
+
+// The Docker container exposes a single port for the unified ingress.
+// With --network host this is accessible at localhost directly.
+const INGRESS_PORT = process.env.MOCK_LLM_INGRESS_PORT ?? "18300";
+
+// Public-mode static server — runs inside the Docker container when
+// PUBLIC_MODE_PORT is set (see docker/entrypoint.sh). With --network host
+// the port is accessible from the host at localhost directly.
+const PUBLIC_MODE_PORT = process.env.MOCK_LLM_PUBLIC_MODE_PORT ?? "18301";
+
+// ── Session API key ────────────────────────────────────────────────────
+const sessionApiKey =
+  process.env.MOCK_LLM_SESSION_API_KEY?.trim() ||
+  randomBytes(32).toString("hex");
+process.env.MOCK_LLM_SESSION_API_KEY = sessionApiKey;
+
+// ── URLs ───────────────────────────────────────────────────────────────
+// The Docker entrypoint starts static-server.mjs with `--host ::` (dual-
+// stack), so it accepts both IPv4 and IPv6 connections — same as the npm
+// path's ingress.mjs.  `localhost` is safe for both configs now.
+// The mock LLM server (Python, host-side) also listens dual-stack.
+const INGRESS_URL = `http://localhost:${INGRESS_PORT}/`;
+const MOCK_LLM_URL = `http://127.0.0.1:${MOCK_LLM_PORT}`;
+
+// Python binary for the mock server — defaults to "python3" but CI can
+// point this at a venv (e.g. ".mock-llm-venv/bin/python3") to avoid
+// PEP 668 "externally managed" errors on Ubuntu 24.04+.
+const MOCK_LLM_PYTHON = process.env.MOCK_LLM_PYTHON ?? "python3";
+
+// Export for the test helpers — BACKEND_URL points to the ingress (API
+// calls are proxied to the agent-server, so no direct backend port needed).
+process.env.MOCK_LLM_BACKEND_URL = `http://localhost:${INGRESS_PORT}`;
+process.env.MOCK_LLM_PORT = MOCK_LLM_PORT;
+process.env.MOCK_LLM_PUBLIC_MODE_URL = `http://localhost:${PUBLIC_MODE_PORT}`;
+process.env.VITE_SESSION_API_KEY = sessionApiKey;
+
+// MOCK_LLM_AGENT_URL — the URL the agent-server inside Docker uses to
+// call the mock LLM for inference. With --network host on Linux the
+// agent-server can reach 127.0.0.1 directly. For macOS/Windows Docker
+// Desktop, override this to http://host.docker.internal:<port>.
+if (!process.env.MOCK_LLM_AGENT_URL) {
+  process.env.MOCK_LLM_AGENT_URL = MOCK_LLM_URL;
+}
+
+// ── Skill test support ────────────────────────────────────────────────
+// The skill tests create git repos and user skill files on the host.
+// We volume-mount these into the container so the agent-server can see them.
+
+// Project skills: host creates repos here, container sees them at a fixed path.
+const SKILL_REPOS_HOST_DIR = resolve(".tmp/mock-llm-skill-repos");
+const SKILL_REPOS_CONTAINER_DIR = "/tmp/mock-llm-skill-repos";
+mkdirSync(SKILL_REPOS_HOST_DIR, { recursive: true });
+process.env.MOCK_LLM_SKILL_REPOS_CONTAINER_DIR = SKILL_REPOS_CONTAINER_DIR;
+
+// User skills: host creates skill files here, container mounts them at
+// the agent-server's expected ~/.openhands/skills/ path.
+const USER_SKILLS_HOST_DIR = resolve(".tmp/mock-llm-user-skills");
+const USER_SKILLS_CONTAINER_DIR = "/home/openhands/.openhands/skills";
+mkdirSync(USER_SKILLS_HOST_DIR, { recursive: true });
+process.env.MOCK_LLM_USER_SKILLS_HOST_DIR = USER_SKILLS_HOST_DIR;
+
+// ── Folder-workspace test support ──────────────────────────────────────
+// The folder-workspace test creates a temp directory on the host that the
+// agent-server's folder browser needs to list. Mount a shared directory into
+// the container at the same path so the agent-server can see it.
+const FOLDER_WORKSPACE_HOST_DIR = resolve(".tmp/e2e-folder-workspace-test");
+const FOLDER_WORKSPACE_CONTAINER_DIR = "/tmp/e2e-folder-workspace-test";
+mkdirSync(FOLDER_WORKSPACE_HOST_DIR, { recursive: true });
+process.env.MOCK_LLM_FOLDER_WORKSPACE_HOST_DIR = FOLDER_WORKSPACE_HOST_DIR;
+process.env.MOCK_LLM_FOLDER_WORKSPACE_CONTAINER_DIR =
+  FOLDER_WORKSPACE_CONTAINER_DIR;
+
+// ── ACP test support ──────────────────────────────────────────────────
+// The mock ACP server script lives on the host. We volume-mount it into
+// the container and tell the test which container-side paths to use when
+// typing the `acp_command` into the Settings UI.
+const MOCK_ACP_HOST_PATH = resolve(
+  "tests/e2e/mock-llm/scripts/mock-acp-server.py",
+);
+const MOCK_ACP_CONTAINER_PATH = "/opt/mock-acp-server.py";
+
+// The agent-server image ships Python 3 via the openhands-sdk base.
+process.env.MOCK_ACP_CONTAINER_PYTHON = "python3";
+process.env.MOCK_ACP_CONTAINER_SCRIPT = MOCK_ACP_CONTAINER_PATH;
+
+const DEFAULT_CI_GLOBAL_TIMEOUT_MS = 1_200_000;
+const configuredCiGlobalTimeoutMs = Number.parseInt(
+  process.env.MOCK_LLM_DOCKER_GLOBAL_TIMEOUT_MS ??
+    String(DEFAULT_CI_GLOBAL_TIMEOUT_MS),
+  10,
+);
+const ciGlobalTimeoutMs = Number.isFinite(configuredCiGlobalTimeoutMs)
+  ? configuredCiGlobalTimeoutMs
+  : DEFAULT_CI_GLOBAL_TIMEOUT_MS;
+
+export default defineConfig({
+  testDir: "./tests/e2e/mock-llm",
+  testMatch: /.*\.spec\.ts/,
+  fullyParallel: false,
+  forbidOnly: !!process.env.CI,
+  // One retry for transient Docker container startup failures.
+  retries: process.env.CI ? 1 : 0,
+  workers: 1,
+  timeout: 60_000,
+  globalTimeout: process.env.CI ? ciGlobalTimeoutMs : 0, // 20 min hard cap in CI
+  reporter: [
+    ["line"],
+    [
+      "json",
+      { outputFile: "test-results-mock-llm-docker/results.json" },
+    ],
+    [
+      "html",
+      {
+        outputFolder: "playwright-report-mock-llm-docker",
+        open: "never",
+      },
+    ],
+    ["./tests/e2e/mock-llm/reporters/done-marker-reporter.ts"],
+  ],
+  outputDir: "test-results-mock-llm-docker",
+  use: {
+    baseURL: INGRESS_URL,
+    screenshot: "only-on-failure",
+    trace: "on-first-retry",
+    video: "on",
+  },
+  projects: [
+    {
+      name: "chromium",
+      use: { ...devices["Desktop Chrome"] },
+    },
+  ],
+  webServer: [
+    // 1. Mock LLM server (Python, on the host)
+    {
+      command: `${MOCK_LLM_PYTHON} tests/e2e/mock-llm/scripts/mock-llm-server.py --port ${MOCK_LLM_PORT}`,
+      url: MOCK_LLM_URL,
+      timeout: 30_000,
+      reuseExistingServer: !process.env.CI,
+      stdout: "pipe",
+      stderr: "pipe",
+    },
+    // 2. Docker container running the agent-canvas all-in-one image
+    //
+    // Uses --network host so the container shares the host's network:
+    //   - The ingress port is available at localhost:<INGRESS_PORT>
+    //   - The agent-server can reach the mock LLM at 127.0.0.1:<MOCK_LLM_PORT>
+    //
+    // The container is started with --rm for auto-cleanup. A named container
+    // is used so the teardown can `docker stop` it reliably.
+    //
+    // Note: --network host is Linux-only. On macOS/Windows Docker Desktop,
+    // use -p port mapping and set MOCK_LLM_AGENT_URL=http://host.docker.internal:<port>.
+    {
+      command: [
+        // Stop any leftover container from a previous failed run
+        `docker rm -f ${CONTAINER_NAME} 2>/dev/null;`,
+        "exec docker run",
+        // Keep the container until the workflow captures its logs.
+        `--name ${CONTAINER_NAME}`,
+        "--network host",
+        // Mount the mock ACP server script so the agent-server inside
+        // Docker can spawn it as an ACP subprocess.
+        `-v ${MOCK_ACP_HOST_PATH}:${MOCK_ACP_CONTAINER_PATH}:ro`,
+        // Mount skill test directories so the agent-server can access
+        // repos and user skills created by the host-side test code.
+        `-v ${SKILL_REPOS_HOST_DIR}:${SKILL_REPOS_CONTAINER_DIR}`,
+        `-v ${USER_SKILLS_HOST_DIR}:${USER_SKILLS_CONTAINER_DIR}`,
+        // Mount the folder-workspace test directory so the agent-server's
+        // folder browser can list/navigate it inside the container.
+        `-v ${FOLDER_WORKSPACE_HOST_DIR}:${FOLDER_WORKSPACE_CONTAINER_DIR}`,
+        `-e PORT=${INGRESS_PORT}`,
+        `-e SESSION_API_KEY=${sessionApiKey}`,
+        `-e OH_SESSION_API_KEYS_0=${sessionApiKey}`,
+        `-e PUBLIC_MODE_PORT=${PUBLIC_MODE_PORT}`,
+        "-e VITE_DO_NOT_TRACK=1",
+        "-e VITE_ENABLE_BROWSER_TOOLS=false",
+        DOCKER_IMAGE,
+      ].join(" "),
+      // Probe the automation list endpoint through the ingress to ensure
+      // the FULL stack (agent-server + automation backend + ingress) is
+      // up before tests start. GET /api/automation/v1 returns 200 (empty
+      // list) without auth — the automation backend does not enforce
+      // session-key auth on the list endpoint.
+      url: `http://localhost:${INGRESS_PORT}/api/automation/v1`,
+      timeout: 180_000, // Docker pull + all services startup
+      reuseExistingServer: !process.env.CI,
+    },
+  ],
+  // globalTeardown stops the Docker container when Playwright exits.
+  // Playwright sends SIGTERM to the webServer command, but `docker run`
+  // with --rm handles cleanup automatically on termination.
+});

playwright.mock-llm.config.ts

@@ -0,0 +1,198 @@
+/**
+ * Playwright config for mock-LLM E2E tests.
+ *
+ * Starts three processes:
+ *   1. Mock LLM server (Python, using openhands-sdk TestLLM)
+ *   2. Full agent-canvas stack via bin/agent-canvas.mjs (agent-server +
+ *      automation backend + static frontend + ingress proxy), matching the
+ *      production npm-published binary.
+ *   3. A second static-server instance with `--auth-required` (public mode)
+ *      on a separate port, proxying to the same backend.  Used by the
+ *      auth-mode E2E tests.
+ *
+ * The test creates an LLM profile via the UI that points at the mock server,
+ * so no real LLM credentials are needed.
+ *
+ * A pre-built `build/` directory is required — the Playwright webServer
+ * command runs `npm run build:app` when `build/index.html` is absent.
+ * CI should run the build step explicitly before the tests for caching.
+ */
+
+import { defineConfig, devices } from "@playwright/test";
+import { randomBytes } from "node:crypto";
+import { dirname, join, resolve } from "node:path";
+
+// ── Port allocation (separate from live E2E / dev to avoid collisions) ─
+const MOCK_LLM_PORT = process.env.MOCK_LLM_PORT ?? "9999";
+
+// The agent-canvas binary exposes a single ingress port that routes:
+//   /api/automation/* → automation backend
+//   /api/*, /sockets  → agent-server
+//   /*                → static frontend
+// Tests use this single URL for both the browser (baseURL) and backend API
+// calls (the ingress proxies /api/* transparently).
+const INGRESS_PORT = process.env.MOCK_LLM_INGRESS_PORT ?? "18300";
+
+// A second static-server instance for public-mode auth tests. It serves
+// the same build/ directory with --auth-required (no baked session key)
+// and proxies to the same backend.
+const PUBLIC_MODE_PORT = process.env.MOCK_LLM_PUBLIC_MODE_PORT ?? "18301";
+
+// ── Session API key ────────────────────────────────────────────────────
+const sessionApiKey =
+  process.env.MOCK_LLM_SESSION_API_KEY?.trim() ||
+  randomBytes(32).toString("hex");
+process.env.MOCK_LLM_SESSION_API_KEY = sessionApiKey;
+
+// ── State directory (isolated per test run) ────────────────────────────
+const STATE_DIR = resolve(".tmp/mock-llm-state");
+
+// Automation DB lives at $parent_of_STATE_DIR/automation/automations.db,
+// mirroring docker/entrypoint.sh which uses $HOME/.openhands/automation/automations.db.
+// Both STATE_DIR and AUTOMATION_DB_DIR must be cleaned between runs to avoid stale data.
+const AUTOMATION_DB_DIR = join(dirname(STATE_DIR), "automation");
+
+// ── URLs ───────────────────────────────────────────────────────────────
+const INGRESS_URL = `http://localhost:${INGRESS_PORT}/`;
+const MOCK_LLM_URL = `http://127.0.0.1:${MOCK_LLM_PORT}`;
+
+// Python binary for the mock server — defaults to "python3" but CI can
+// point this at a venv (e.g. ".mock-llm-venv/bin/python3") to avoid
+// PEP 668 "externally managed" errors on Ubuntu 24.04+.
+const MOCK_LLM_PYTHON = process.env.MOCK_LLM_PYTHON ?? "python3";
+
+// Export for the test helpers — BACKEND_URL points to the ingress (API
+// calls are proxied to the agent-server, so no direct backend port needed).
+process.env.MOCK_LLM_BACKEND_URL = `http://localhost:${INGRESS_PORT}`;
+process.env.MOCK_LLM_PORT = MOCK_LLM_PORT;
+process.env.MOCK_LLM_PUBLIC_MODE_URL = `http://localhost:${PUBLIC_MODE_PORT}`;
+
+function shellQuote(value: string) {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function envAssignment(name: string, value: string) {
+  return `${name}=${shellQuote(value)}`;
+}
+
+const DEFAULT_CI_GLOBAL_TIMEOUT_MS = 1_200_000;
+const configuredCiGlobalTimeoutMs = Number.parseInt(
+  process.env.MOCK_LLM_GLOBAL_TIMEOUT_MS ??
+    String(DEFAULT_CI_GLOBAL_TIMEOUT_MS),
+  10,
+);
+const ciGlobalTimeoutMs = Number.isFinite(configuredCiGlobalTimeoutMs)
+  ? configuredCiGlobalTimeoutMs
+  : DEFAULT_CI_GLOBAL_TIMEOUT_MS;
+
+export default defineConfig({
+  testDir: "./tests/e2e/mock-llm",
+  testMatch: /.*\.spec\.ts/,
+  fullyParallel: false,
+  forbidOnly: !!process.env.CI,
+  retries: 0,
+  workers: 1,
+  timeout: 60_000,
+  globalTimeout: process.env.CI ? ciGlobalTimeoutMs : 0, // 20 min hard cap in CI
+  reporter: [
+    ["line"],
+    ["json", { outputFile: "test-results-mock-llm/results.json" }],
+    ["html", { outputFolder: "playwright-report-mock-llm", open: "never" }],
+    ["./tests/e2e/mock-llm/reporters/done-marker-reporter.ts"],
+  ],
+  outputDir: "test-results-mock-llm",
+  use: {
+    baseURL: INGRESS_URL,
+    screenshot: "only-on-failure",
+    trace: "on-first-retry",
+    video: "on",
+  },
+  projects: [
+    {
+      name: "chromium",
+      use: { ...devices["Desktop Chrome"] },
+    },
+  ],
+  webServer: [
+    // 1. Mock LLM server (Python)
+    {
+      command: `${MOCK_LLM_PYTHON} tests/e2e/mock-llm/scripts/mock-llm-server.py --port ${MOCK_LLM_PORT}`,
+      url: MOCK_LLM_URL,
+      timeout: 30_000,
+      reuseExistingServer: !process.env.CI,
+      stdout: "pipe",
+      stderr: "pipe",
+    },
+    // 2. Full agent-canvas stack via bin/agent-canvas.mjs
+    //
+    // This mirrors the production `npx @openhands/agent-canvas` path:
+    //   - Pre-built static frontend served via static-server.mjs
+    //   - Agent-server via uvx
+    //   - Automation backend via uvx
+    //   - Ingress proxy unifying all routes on a single port
+    //
+    // `exec` replaces the shell so Playwright's tracked PID IS the node
+    // process. SIGTERM goes directly to the shutdown handler, which
+    // kills children via process groups and exits cleanly.
+    {
+      command:
+        // Clean state dir and automation DB dir to avoid stale data between runs.
+        // Automation DB is stored outside STATE_DIR (at AUTOMATION_DB_DIR) so both
+        // must be cleaned; see scripts/dev-with-automation.mjs startAutomationBackend.
+        `node -e "const fs=require('node:fs'); fs.rmSync('${STATE_DIR}',{recursive:true,force:true}); fs.rmSync('${AUTOMATION_DB_DIR}',{recursive:true,force:true});" && ` +
+        // Build frontend if not already built (CI should pre-build for caching)
+        "[ -f build/index.html ] || npm run build:app && " +
+        [
+          "exec env",
+          envAssignment("OH_CANVAS_SAFE_STATE_DIR", STATE_DIR),
+          envAssignment("PORT", INGRESS_PORT),
+          envAssignment("LOCAL_BACKEND_API_KEY", sessionApiKey),
+          "VITE_DO_NOT_TRACK=1",
+          "VITE_ENABLE_BROWSER_TOOLS=false",
+          // Bypass npm — exec directly into node so SIGTERM reaches
+          // the shutdown handler (npm swallows it).
+          "node --env-file-if-exists=.env bin/agent-canvas.mjs",
+        ].join(" "),
+      // Probe the automation list endpoint through the ingress to ensure
+      // the FULL stack (agent-server + automation backend + ingress) is
+      // up before tests start. The automation backend starts last via
+      // uvx and can take 30-60s — checking only the ingress root or
+      // /server_info would let tests begin before it's ready.
+      // GET /api/automation/v1 returns 200 (empty list) without auth
+      // because the dev automation backend does not enforce session-key
+      // auth on the list endpoint (confirmed in CI).
+      url: `http://localhost:${INGRESS_PORT}/api/automation/v1`,
+      timeout: 180_000, // allow extra time for build + agent-server + automation startup
+      reuseExistingServer: !process.env.CI,
+      // Without this, Playwright tears the webServer down with
+      // process.kill(-pid, "SIGKILL"), which the stack cannot catch. Its
+      // services are spawned detached (see scripts/dev-process-utils.mjs), so
+      // they sit in their own process groups and survive that group kill,
+      // orphaning to PID 1 while still holding 18000/18001/18300/3001. Asking
+      // for SIGTERM lets the existing shutdown handler in
+      // scripts/dev-with-automation.mjs run, which stops each service, waits
+      // 3s, then force-kills stragglers. The timeout below leaves headroom
+      // over that 3s pass.
+      gracefulShutdown: { signal: "SIGTERM", timeout: 15_000 },
+    },
+    // 3. Public-mode static server — same build/, same backend, but with
+    //    --auth-required (no session key injected). The agent-server's
+    //    internal ports are the defaults from config/defaults.json (18000
+    //    for agent-server, 18001 for automation).
+    {
+      command: [
+        "exec node scripts/static-server.mjs",
+        "--dir build",
+        `--port ${PUBLIC_MODE_PORT}`,
+        "--auth-required",
+        "--route /api/automation=http://localhost:18001",
+        "--route /api=http://localhost:18000",
+        "--route /server_info=http://localhost:18000",
+        "--route /sockets=http://localhost:18000",
+      ].join(" "),
+      url: `http://localhost:${PUBLIC_MODE_PORT}/`,
+      timeout: 15_000,
+      reuseExistingServer: !process.env.CI,
+    },
+  ],
+});

react-router.config.ts

@@ -0,0 +1,94 @@
+import type { Config } from "@react-router/dev/config";
+import { vercelPreset } from "@vercel/react-router/vite";
+
+const normalizeBasePath = (value?: string) => {
+  const raw = value?.trim();
+  if (!raw || raw === "/") return undefined;
+
+  const withLeadingSlash = raw.startsWith("/") ? raw : `/${raw}`;
+  return withLeadingSlash.replace(/\/+$/, "");
+};
+
+const basename = normalizeBasePath(process.env.VITE_BASE_PATH);
+
+/**
+ * This script is used to unpack the client directory from the frontend build directory.
+ * Remix SPA mode builds the client directory into the build directory. This function
+ * moves the contents of the client directory to the build directory and then removes the
+ * client directory.
+ *
+ * This script is used in the buildEnd function of the Vite config.
+ */
+let unpackClientDirectoryPromise: Promise<void> | null = null;
+
+const moveBuildEntry = async (
+  fs: typeof import("fs"),
+  source: string,
+  destination: string,
+) => {
+  await fs.promises.rm(destination, { recursive: true, force: true });
+
+  try {
+    await fs.promises.rename(source, destination);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code !== "EPERM" && code !== "EXDEV") {
+      throw error;
+    }
+
+    await fs.promises.cp(source, destination, {
+      recursive: true,
+      force: true,
+    });
+    await fs.promises.rm(source, { recursive: true, force: true });
+  }
+};
+
+const unpackClientDirectoryOnce = async () => {
+  if (process.env.VERCEL) {
+    // Vercel's React Router builder reads static assets from build/client.
+    return;
+  }
+
+  const fs = await import("fs");
+  const path = await import("path");
+
+  const buildDir = path.resolve(__dirname, "build");
+  const clientDir = path.resolve(buildDir, "client");
+
+  let files: string[];
+  try {
+    files = await fs.promises.readdir(clientDir);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return;
+    }
+    throw error;
+  }
+
+  for (const file of files) {
+    await moveBuildEntry(
+      fs,
+      path.resolve(clientDir, file),
+      path.resolve(buildDir, file),
+    );
+  }
+
+  await fs.promises.rm(clientDir, { recursive: true, force: true });
+};
+
+const unpackClientDirectory = async () => {
+  unpackClientDirectoryPromise ??= unpackClientDirectoryOnce().finally(() => {
+    unpackClientDirectoryPromise = null;
+  });
+
+  await unpackClientDirectoryPromise;
+};
+
+export default {
+  appDirectory: "src",
+  ...(basename ? { basename } : {}),
+  buildEnd: unpackClientDirectory,
+  presets: [vercelPreset()],
+  ssr: false,
+} satisfies Config;

release-please-config.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "include-component-in-tag": false,
+  "include-v-in-tag": true,
+  "draft-pull-request": true,
+  "packages": {
+    ".": {
+      "release-type": "node",
+      "changelog-type": "github",
+      "skip-changelog": true,
+      "extra-files": [
+        {
+          "type": "json",
+          "path": "config/defaults.json",
+          "jsonpath": "$.versions.agentCanvas"
+        },
+        {
+          "_comment": "Must stay `generic` (annotation-driven). A bare \"helm/agent-canvas/Chart.yaml\" string would resolve to CompositeUpdater(GenericYaml('$.version'), Generic), which overwrites the chart-level `version` and strips every comment in the file when js-yaml re-serializes it.",
+          "type": "generic",
+          "path": "helm/agent-canvas/Chart.yaml"
+        },
+        "README.md",
+        "README.windows.md"
+      ]
+    }
+  }
+}

specs/backend-management.md

@@ -0,0 +1,12 @@
+# Backend Management Specs
+
+---
+
+### BM-001: Auto-switch on connect
+- [x] Adding a backend shall automatically switch the active selection to it.
+
+### BM-002: Switching backends keeps the user on the same page
+- [x] Switching backends shall redirect to the same section but on the new backend. The user shall never see stale data from the previous backend.
+
+### BM-003: Fallback on active backend removal
+- [x] Removing the currently active backend shall fall back to a remaining local backend. The user shall never be left without an active backend.

specs/canvas-extensions.md

@@ -0,0 +1,283 @@
+# Canvas Extensions
+
+## Status
+
+Implementation plan and v1 contract. The frontend vertical slice may ship behind
+Agent Server capability detection while the backend endpoints are implemented.
+
+## Product definition
+
+Canvas Extensions are installable packages that change Agent Canvas itself.
+They contribute UI and local product behavior such as routed pages, conversation
+panels, renderers, slots, and themes. Skills and plugins change the agent;
+Canvas Extensions change the app.
+
+The Customize area remains the single inventory for Skills, Plugins, MCP, and
+Canvas Extensions. The inventory item is named **Extensions**; "addon" is an
+informal alias only.
+
+## Decisions
+
+1. **The active Agent Server owns extensions.** An extension is installed on the
+   computer or container running the Agent Server. Its source, resolved revision,
+   files, manifest, and enabled state live there. Canvas only discovers and loads
+   extensions from the currently active backend. Switching backends replaces the
+   active extension set.
+2. **Extension code is trusted, same-realm code.** There is no iframe, worker
+   sandbox, or granular permission system. Once enabled, an extension has the
+   same ambient browser authority as Canvas code. Shadow DOM may be offered later
+   as optional style isolation, but never as a security boundary.
+3. **Install and enable are separate.** Installation always produces a disabled
+   extension. An agent may install or update an extension, but the user returns
+   to Customize -> Extensions and explicitly enables it. In v1 this is a product
+   consent invariant, not proof of human presence against an agent that can call
+   the same authenticated APIs. A future backend policy may allow agent-driven
+   enablement.
+4. **Enablement is hot.** Enabling loads and activates the extension without an
+   app or Agent Server restart. Disabling unmounts registered surfaces and calls
+   lifecycle cleanup. Because code is trusted same-realm JavaScript, cleanup is
+   best-effort; an extension can create global effects the host cannot revoke.
+5. **Distribution follows plugins, not their runtime.** Install coordinates are
+   `source`, optional `ref`, and optional `repo_path`, resolved and pinned by the
+   Agent Server. A repository may contain multiple extensions and other artifact
+   types under subpaths. Backend-local paths are interpreted on the backend
+   machine, never in the frontend process.
+6. **Updates preserve enablement.** Refresh resolves and installs a new revision
+   atomically and keeps the prior enabled state. The UI shows the resulting
+   resolved revision. Since v1 is a trusted-code model, there is no misleading
+   permission-diff approval gate. The staged check/apply flow currently exists
+   only at the Agent Server service layer; until it is exposed over HTTP, the
+   Customize UI offers no Refresh action.
+
+## Trust disclosure
+
+Before enabling, Canvas says plainly that the extension can access and modify the
+Canvas page and can make authenticated requests available to the current browser
+session. The review screen shows source, requested ref, resolved revision,
+manifest metadata, and contributed surfaces. It does not show fictitious
+fine-grained permissions.
+
+Install and update are still meaningful trust actions because they select the
+code revision stored by the backend. Enable is the explicit point at which Canvas
+executes that code.
+
+## Package contract
+
+The manifest filename is `canvas-extension.json`.
+
+```json
+{
+  "schema_version": 1,
+  "name": "example-dashboard",
+  "display_name": "Example dashboard",
+  "version": "0.1.0",
+  "description": "A backend-specific project dashboard.",
+  "entrypoint": "dist/extension.js",
+  "contributes": {
+    "pages": [
+      {
+        "id": "dashboard",
+        "title": "Dashboard",
+        "path": "/dashboard",
+        "nav_label": "Dashboard"
+      }
+    ]
+  }
+}
+```
+
+Rules for v1:
+
+- `name` and contribution IDs use lowercase letters, digits, and hyphens.
+- Page `path` values are absolute kebab-case routes (leading `/`); Canvas
+  mounts them relative to `/extensions/{name}`.
+- `entrypoint` is a path inside the installed package.
+- The entrypoint is one self-contained browser ESM bundle. It must not contain
+  unresolved bare imports or external chunks; dependencies, CSS, and small
+  assets are bundled or embedded by the authoring template.
+- The backend validates that the manifest, entrypoint, and any future asset path
+  remain inside the installed extension root.
+- Host compatibility fields will be added before marketplace distribution. The
+  initial schema is intentionally small while the page ABI is proven by a
+  separately built sample extension.
+
+The v1 module exports `activate`:
+
+```ts
+export function activate(host: CanvasExtensionHost): void | (() => void) {
+  return host.registerPage("dashboard", ({ container, path, navigate }) => {
+    container.textContent = `Extension route: ${path}`;
+    return () => container.replaceChildren();
+  });
+}
+```
+
+`CanvasExtensionHost` is versioned independently from the manifest. The first
+host API contains:
+
+- `apiVersion: "1"`
+- immutable extension/backend metadata
+- `registerPage(id, mount)` for page factories declared by the manifest
+- `navigate(path)` using Canvas base-path-aware routing
+- `agentServer.request(...)`, an authenticated request helper targeting the
+  extension's owning backend
+
+The runtime fetches the bundle as authenticated text and imports it through a
+temporary Blob URL. A direct `<script src>` or `import(backendUrl)` cannot carry
+`X-Session-API-Key`, so it is not the v1 loading path. Importing the bundle does
+not activate it; Canvas calls `activate` only for an enabled installation.
+
+## Agent Server API
+
+The API deliberately mirrors plugin distribution management while remaining a
+separate runtime:
+
+| Method   | Path                                              | Purpose                                                   |
+| -------- | ------------------------------------------------- | --------------------------------------------------------- |
+| `GET`    | `/api/canvas-extensions/installed`                | List installed extensions and parsed manifests            |
+| `POST`   | `/api/canvas-extensions/install`                  | Install from git or a backend-local path; always disabled |
+| `GET`    | `/api/canvas-extensions/installed/{name}`         | Read one installation                                     |
+| `PATCH`  | `/api/canvas-extensions/installed/{name}`         | Set enabled state                                         |
+| `DELETE` | `/api/canvas-extensions/installed/{name}`         | Uninstall                                                 |
+| `GET`    | `/api/canvas-extensions/installed/{name}/bundle`  | Return the entrypoint as JavaScript text                  |
+
+A refresh endpoint (`POST /api/canvas-extensions/installed/{name}/refresh`) is
+planned but not part of the current router; the service-layer staged check/apply
+flow backs it and is tracked separately.
+
+The list endpoint wraps its results in a `canvas_extensions` array.
+
+Install request:
+
+```json
+{
+  "source": "github:owner/repository",
+  "ref": "main",
+  "repo_path": "extensions/example-dashboard",
+  "force": false
+}
+```
+
+Installed response:
+
+```json
+{
+  "name": "example-dashboard",
+  "version": "0.1.0",
+  "description": "A backend-specific project dashboard.",
+  "enabled": false,
+  "source": "github:owner/repository",
+  "resolved_ref": "6f5f9a...",
+  "repo_path": "extensions/example-dashboard",
+  "installed_at": "2026-08-01T12:00:00Z",
+  "install_path": "/home/user/.openhands/canvas-extensions/installed/example-dashboard",
+  "manifest": {}
+}
+```
+
+The `manifest` field (parsed `canvas-extension.json`, including
+`contributes.pages`) is not returned by the current router yet; until it ships,
+Canvas treats it as optional and renders installations without page
+contributions or a display name.
+
+The backend must prevent install requests from setting `enabled: true`. The
+frontend's enable control calls the patch endpoint. Backend authorization and
+multi-user installation scope follow the Agent Server deployment's existing
+session trust model; v1 does not introduce a separate approval credential.
+
+Until the API exists, Canvas treats HTTP 404 as "this backend does not support
+Canvas Extensions". Customize shows an upgrade message, while the global runtime
+stays silent. It must not collapse unsupported, unreachable, and an empty
+inventory into the same state.
+
+## Frontend runtime
+
+The runtime is keyed by backend ID, organization scope, and connection revision.
+This prevents an enabled bundle or cached inventory from one backend appearing
+on another after a switch or reconnect.
+
+For each enabled installation:
+
+1. Fetch the authenticated entrypoint text from the owning backend.
+2. Import the self-contained ESM bundle from a Blob URL.
+3. Validate `activate` and its host API version.
+4. Create an extension-scoped registry and call `activate`.
+5. Admit registrations only when their IDs were declared in the manifest.
+6. Render each surface inside an error boundary owned by Canvas.
+7. On disable, uninstall, update, or backend switch, unmount every surface,
+   invoke the extension disposer, and remove its registry entries.
+
+The initial route shape is
+`/extensions/{extension-name}/{declared-page-path}`. `/extensions` itself is the
+Customize inventory. All routing goes through React Router so `VITE_BASE_PATH`
+continues to work.
+
+## Delivery plan
+
+### Slice 1: contract and management
+
+- Land this spec and shared TypeScript manifest/installation types.
+- Add a backend-keyed service and query hooks for list, install, enable/disable,
+  uninstall, and authenticated bundle fetch.
+- Add Customize -> Extensions with an unsupported-backend state, source install
+  form, source/revision/contribution review, and explicit enable control.
+- Keep the global runtime silent when the active backend returns 404.
+
+### Slice 2: routed page proof
+
+- Add the versioned host API, module loader, lifecycle registry, and error
+  boundary.
+- Add dynamic page routes and left-rail navigation for enabled page
+  contributions.
+- Build a standalone fixture extension with the same scaffold authors will use.
+- Verify enable, hot activation, navigation, disable cleanup, update, backend
+  switching, session-key-authenticated bundle loading, and `VITE_BASE_PATH`.
+
+### Slice 3: theme proof
+
+- Define a code-free theme contribution with a strict Canvas token schema.
+- Validate theme manifests on the backend and surface installed themes in
+  Settings.
+- Keep theme selection browser/user scoped while availability follows the active
+  backend; fall back cleanly when switching away from the providing backend.
+
+### Slice 4: conversation surfaces
+
+- Replace the closed conversation tab union with namespaced runtime IDs and
+  centralized persistence admission.
+- Add extension tabs/panels, then host-owned header/footer/badge slots.
+- Define mobile behavior, ordering, conflicts, missing-extension fallback, and
+  per-conversation lifecycle context before opening each surface to authors.
+
+### Slice 5: visualizers and authoring loop
+
+- Add augment/replace visualizer registrations with explicit event matching,
+  precedence, and built-in fallback.
+- Publish the stable extension SDK types, bundler template, validation command,
+  and sample repository.
+- Only then ship `/build-canvas-extension`, including backend-local versus remote
+  workspace guidance, temporary install, manual enable instructions, and git
+  publication/update flow.
+
+## Verification
+
+Each slice adds service and runtime unit tests. The routed page slice also adds a
+mock-LLM end-to-end spec (`tests/e2e/mock-llm/canvas-extensions/`) that drives
+the production build through install → enable → page render → disable →
+uninstall. Until the pinned agent-server ships the endpoints, the spec serves
+the API contract from `src/fixtures/canvas-extensions/demo-page` through
+Playwright route interception; once it does, the stub is removed and the same
+steps run against the real backend.
+Changing the mock-LLM feature layout or mapping requires updating `AGENTS.md` in
+the same change. Before merge, run `npm run lint`, `npm test`, `npm run build`,
+and `npm run build:lib`.
+
+## Explicit non-goals for v1
+
+- iframe/worker isolation or enforceable fine-grained permissions
+- arbitrary lifecycle scripts during installation
+- automatic enablement by agents
+- marketplace ranking or publisher signing
+- conversation tabs, slots, or visualizer replacement in the first vertical
+  slice
+- treating `@openhands/extensions` as an installable runtime format

specs/llm-defaults.md

@@ -0,0 +1,10 @@
+# LLM Defaults Specs
+
+---
+
+### LLD-001: Frontend always sends its chosen default model
+
+- [x] When the agent-server returns an absent or empty `llm.model` (e.g. because the user has never saved settings), the frontend adapter shall substitute `DEFAULT_SETTINGS.llm_model` (`"openai/gpt-5.6-sol"`) before sending the conversation-start request.
+- [x] The frontend shall never rely on the agent-server SDK's own default model (`gpt-5.5`); it shall always send an explicit model value.
+- [x] Whitespace-only model strings shall be treated as absent and fall back to the default.
+- [x] The same guard applies when LLM settings arrive via `encryptedAgentSettings` (the conversation-start encrypted payload path).

specs/mcp-settings.md

@@ -0,0 +1,28 @@
+# MCP Settings Specs
+
+---
+
+### MCP-001: Sparse mutations preserve sibling servers
+
+- [x] Adding, updating, or deleting an MCP server shall issue exactly one
+      dedicated MCP settings request containing only the affected server.
+- [x] An MCP mutation shall never use redacted or encrypted settings snapshots
+      as its mutation base.
+- [x] Untouched sibling servers and credentials shall survive add, update,
+      delete, concurrent different-key updates, and failed mutations.
+
+### MCP-002: Secret patches preserve user intent
+
+- [x] Omitting an unchanged secret shall preserve its stored value.
+- [x] Supplying a secret shall replace its stored value.
+- [x] Explicitly clearing a supported secret field shall send `null`.
+- [x] The display-only redaction sentinel shall never be sent as mutation data.
+
+### MCP-003: Settings map keys are stable MCP identities
+
+- [x] Rendering order and transport grouping shall not change persistence
+      identity.
+- [x] Deletion shall address the settings map key without matching URL, command,
+      or arguments.
+- [x] Rename shall use one atomic map patch, reject collisions, and reject
+      hidden-secret renames that could lose credentials.

specs/workspace-upload-path.md

@@ -0,0 +1,16 @@
+# Workspace Upload Path Specs
+
+---
+
+### WUP-001: Relative working dirs are resolved against `/api/file/home`, not the filesystem root
+- [x] When the frontend creates a conversation and the resolved working dir is **relative** (e.g. the `DEFAULT_WORKING_DIR = "workspace/project"` fallback), `AgentServerConversationService.createConversation` shall resolve it to an **absolute** path before sending `workspace.working_dir` to the agent-server, by prefixing the agent-server's home directory as returned by `GET /api/file/home`.
+- [x] When the frontend uploads a file, `buildWorkspaceUploadPath` shall resolve the conversation's working dir through the same home-directory anchor, so the upload destination always matches the conversation's worktree location.
+- [x] When the working dir is already absolute (e.g. POSIX `/foo`, Windows `C:\foo`, or the explicit selection from `search_subdirs`), the resolver shall pass it through unchanged.
+- [x] The home-directory lookup shall be cached per backend host so concurrent uploads share a single in-flight `/api/file/home` request, and a cached value is reused for subsequent uploads.
+- [x] A failed lookup shall not be cached so the next call retries fresh.
+- [x] Upload paths shall never be constructed by naively prepending `/`; the legacy `toAbsoluteWorkspacePath` helper that did so was removed once its last callers disappeared (recoverable from git history), and the home-anchored resolver is the only sanctioned mechanism.
+
+### Why this exists
+- The agent-server's `/api/file/upload` endpoint requires an absolute path and `mkdir -p`s the parent of the destination. Naively prepending `/` to the default `workspace/project/<hex>` produces `/workspace/project/<hex>`. On macOS and on fresh Docker images that mount only `/home/<user>` as writable, the filesystem root is read-only, so the upload fails with `OSError: [Errno 30] Read-only file system: '/workspace'`.
+- The agent-server otherwise interprets a relative `workspace.working_dir` against its process CWD (which is whichever directory the launcher used), so absent this resolver, the conversation's worktree lands in one place and the upload tries to land in a totally different place.
+- `/api/file/home` is the most reliable absolute, writable anchor the agent-server API currently exposes; `/server_info` does not include the CWD.

stryker.config.mjs

@@ -0,0 +1,22 @@
+// @ts-check
+
+/** @type {import("@stryker-mutator/api/core").PartialStrykerOptions} */
+const config = {
+  testRunner: "vitest",
+  mutate: [
+    "src/**/*.{ts,tsx}",
+    "!src/**/*.{test,spec}.{ts,tsx}",
+    "!src/**/__tests__/**",
+    "!src/**/*.d.ts",
+    "!src/**/*.types.ts",
+    "!src/**/*.{gen,generated}.{ts,tsx}",
+    "!src/i18n/declaration.ts",
+    "!src/{fixtures,mocks,dev}/**",
+  ],
+  vitest: {
+    configFile: "vite.config.ts",
+    related: true,
+  },
+};
+
+export default config;

tailwind.config.js

@@ -0,0 +1,59 @@
+/** @type {import('tailwindcss').Config} */
+import typography from "@tailwindcss/typography";
+export default {
+  darkMode: "class",
+  theme: {
+    extend: {
+      colors: {
+        modal: {
+          background: "#171717",
+          input: "#27272A",
+          primary: "#F3CE49",
+          secondary: "#737373",
+          muted: "#A3A3A3",
+        },
+        surface: {
+          DEFAULT: "#050505",
+          card: "#0a0a0a",
+          elevated: "#1a1a1a",
+          outline: "#171717",
+          background: "#262626",
+          divider: "#525252",
+          button: "#737373",
+          text: "#A3A3A3",
+        },
+        border: {
+          DEFAULT: "#242424",
+          hover: "#3a3a3a",
+        },
+        content: {
+          DEFAULT: "#fafafa",
+          muted: "#8c8c8c",
+          icon: "#3a3a3a",
+        },
+        status: {
+          "success-bg": "rgba(16, 185, 129, 0.1)",
+          "success-border": "rgba(16, 185, 129, 0.4)",
+          "success-text": "#6ee7b7",
+          "success-badge-bg": "rgba(16, 185, 129, 0.15)",
+          "fail-bg": "rgba(244, 63, 94, 0.1)",
+          "fail-border": "rgba(244, 63, 94, 0.4)",
+          "fail-text": "#fda4af",
+          "fail-solid": "#dc2626",
+          "fail-solid-hover": "#b91c1c",
+        },
+        toggle: {
+          active: "#34d399",
+          "active-bg": "rgba(52, 211, 153, 0.2)",
+          "active-border": "rgba(52, 211, 153, 0.5)",
+          inactive: "#242424",
+          "inactive-knob": "#8c8c8c",
+          "inactive-border": "#3a3a3a",
+        },
+        "muted-overlay": "rgba(5, 5, 5, 0.4)",
+        "pill-bg": "rgba(31, 31, 31, 0.3)",
+      },
+    },
+  },
+  plugins: [typography],
+};

test-utils.tsx

@@ -0,0 +1,232 @@
+import React, { PropsWithChildren } from "react";
+import { RenderOptions, render } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { I18nextProvider, initReactI18next } from "react-i18next";
+import i18n from "i18next";
+import { vi } from "vitest";
+import { AxiosError } from "axios";
+import {
+  ActionEvent,
+  MessageEvent,
+  ObservationEvent,
+  PlanningFileEditorObservation,
+} from "#/types/agent-server/core";
+import {
+  NavigationProvider,
+  type NavigationContextValue,
+} from "#/context/navigation-context";
+import { SecurityRisk } from "#/types/agent-server/core";
+
+export const useParamsMock = vi.fn(() => ({
+  conversationId: "test-conversation-id",
+}));
+
+// Mock useParams before importing components
+vi.mock("react-router", async () => {
+  const actual =
+    await vi.importActual<typeof import("react-router")>("react-router");
+  return {
+    ...actual,
+    useParams: useParamsMock,
+    useRevalidator: () => ({
+      revalidate: vi.fn(),
+    }),
+  };
+});
+
+// Initialize i18n for tests - return key when translation is missing
+i18n.use(initReactI18next).init({
+  lng: "en",
+  fallbackLng: "en",
+  ns: ["translation", "openhands"],
+  defaultNS: "translation",
+  resources: {
+    en: {
+      translation: {},
+      openhands: {},
+    },
+  },
+  interpolation: {
+    escapeValue: false,
+  },
+  returnEmptyString: false,
+  missingKeyHandler: false,
+  saveMissing: false,
+});
+
+const createNavigationValue = (
+  overrides: Partial<NavigationContextValue> = {},
+): NavigationContextValue => ({
+  currentPath: "/",
+  conversationId: "test-conversation-id",
+  isNavigating: false,
+  navigate: vi.fn(),
+  ...overrides,
+});
+
+// This type interface extends the default options for render from RTL
+interface ExtendedRenderOptions extends Omit<RenderOptions, "queries"> {
+  navigation?: Partial<NavigationContextValue>;
+}
+
+// Export our own customized renderWithProviders function that renders with QueryClient and i18next providers
+// Since we're using Zustand stores, we don't need a Redux Provider wrapper
+export function renderWithProviders(
+  ui: React.ReactElement,
+  renderOptions: ExtendedRenderOptions = {},
+) {
+  const { navigation, ...rtlRenderOptions } = renderOptions;
+  const navigationValue = createNavigationValue(navigation);
+
+  function Wrapper({ children }: PropsWithChildren) {
+    return (
+      <QueryClientProvider
+        client={
+          new QueryClient({
+            defaultOptions: { queries: { retry: false } },
+          })
+        }
+      >
+        <I18nextProvider i18n={i18n}>
+          <NavigationProvider value={navigationValue}>
+            {children}
+          </NavigationProvider>
+        </I18nextProvider>
+      </QueryClientProvider>
+    );
+  }
+  return render(ui, { wrapper: Wrapper, ...rtlRenderOptions });
+}
+
+export const createAxiosNotFoundErrorObject = () =>
+  new AxiosError(
+    "Request failed with status code 404",
+    "ERR_BAD_REQUEST",
+    undefined,
+    undefined,
+    {
+      status: 404,
+      statusText: "Not Found",
+      data: { message: "Settings not found" },
+      headers: {},
+      // @ts-expect-error - we only need the response object for this test
+      config: {},
+    },
+  );
+
+export const createAxiosError = (
+  status: number,
+  statusText: string,
+  data: unknown,
+) =>
+  new AxiosError(
+    `Request failed with status code ${status}`,
+    "ERR_BAD_REQUEST",
+    undefined,
+    undefined,
+    {
+      status,
+      statusText,
+      data,
+      headers: {},
+      // @ts-expect-error - we only need the response object for this test
+      config: {},
+    },
+  );
+
+// Helper to create a PlanningFileEditorAction event
+export const createPlanningFileEditorActionEvent = (
+  id: string,
+): ActionEvent => ({
+  id,
+  timestamp: new Date().toISOString(),
+  source: "agent",
+  thought: [{ type: "text", text: "Planning action" }],
+  thinking_blocks: [],
+  action: {
+    kind: "PlanningFileEditorAction",
+    command: "create",
+    path: "/workspace/PLAN.md",
+    file_text: "Plan content",
+    old_str: null,
+    new_str: null,
+    insert_line: null,
+    view_range: null,
+  },
+  tool_name: "planning_file_editor",
+  tool_call_id: "call-1",
+  tool_call: {
+    id: "call-1",
+    type: "function",
+    function: {
+      name: "planning_file_editor",
+      arguments: '{"command": "create"}',
+    },
+  },
+  llm_response_id: "response-1",
+  security_risk: SecurityRisk.UNKNOWN,
+});
+
+// Helper to create a non-planning action event
+export const createOtherActionEvent = (id: string): ActionEvent => ({
+  id,
+  timestamp: new Date().toISOString(),
+  source: "agent",
+  thought: [{ type: "text", text: "Other action" }],
+  thinking_blocks: [],
+  action: {
+    kind: "ExecuteBashAction",
+    command: "echo test",
+    is_input: false,
+    timeout: null,
+    reset: false,
+  },
+  tool_name: "execute_bash",
+  tool_call_id: "call-1",
+  tool_call: {
+    id: "call-1",
+    type: "function",
+    function: {
+      name: "execute_bash",
+      arguments: '{"command": "echo test"}',
+    },
+  },
+  llm_response_id: "response-1",
+  security_risk: SecurityRisk.UNKNOWN,
+});
+
+// Helper to create a PlanningFileEditorObservation event
+export const createPlanningObservationEvent = (
+  id: string,
+  actionId: string = "action-1",
+): ObservationEvent<PlanningFileEditorObservation> => ({
+  id,
+  timestamp: new Date().toISOString(),
+  source: "environment",
+  tool_name: "planning_file_editor",
+  tool_call_id: "call-1",
+  action_id: actionId,
+  observation: {
+    kind: "PlanningFileEditorObservation",
+    content: [{ type: "text", text: "Plan content" }],
+    is_error: false,
+    command: "create",
+    path: "/workspace/PLAN.md",
+    prev_exist: false,
+    old_content: null,
+    new_content: "Plan content",
+  },
+});
+
+// Helper to create a user message event
+export const createUserMessageEvent = (id: string): MessageEvent => ({
+  id,
+  timestamp: new Date().toISOString(),
+  source: "user",
+  llm_message: {
+    role: "user",
+    content: [{ type: "text", text: "User message" }],
+  },
+  activated_skills: [],
+  extended_content: [],
+});

tools/canvas_ui_tool.py

@@ -0,0 +1,158 @@
+"""Legacy conversation compatibility for the former Python Canvas UI tool.
+
+New conversations define ``canvas_ui_control`` through the agent-server's
+``client_tools`` JSON API. The distinct name avoids colliding with this
+process-global legacy registration. This module remains importable because
+persisted conversations store
+``tool_module_qualnames = {"canvas_ui": "canvas_ui_tool"}`` and may contain
+``CanvasUIAction`` / ``CanvasUIObservation`` events. Agent-server imports the
+module before restoring those conversations so the legacy event kinds and tool
+registration remain resolvable.
+
+The server-side executor is a no-op that returns an acknowledgment. The actual
+UI effect happens client-side: the frontend watches the WebSocket stream for
+legacy ``canvas_ui`` and current ``canvas_ui_control`` ActionEvents and dispatches
+the command.
+
+The launchers also import this module at agent-server startup
+(``--import-modules canvas_ui_tool``) so the builtin ``FinishTool`` registration
+at the bottom runs before any conversation is created.
+"""
+
+from collections.abc import Sequence
+from typing import Literal
+
+from pydantic import Field
+
+from openhands.sdk import Action, Observation, ToolDefinition
+from openhands.sdk.tool import (
+    FinishTool,
+    ToolAnnotations,
+    ToolExecutor,
+    list_registered_tools,
+    register_tool,
+)
+
+
+CanvasCommand = Literal["navigate_to_file", "open_tab", "show_preview"]
+CanvasTab = Literal[
+    "files", "browser", "vscode", "terminal", "planner", "tasklist"
+]
+
+
+class CanvasUIAction(Action):
+    """Direct the Agent Canvas frontend to perform a UI action."""
+
+    command: CanvasCommand = Field(description="UI command to dispatch.")
+    path: str | None = Field(
+        default=None,
+        description=(
+            "Workspace-relative file path. Required for navigate_to_file and "
+            "show_preview; ignored otherwise."
+        ),
+    )
+    tab: CanvasTab | None = Field(
+        default=None,
+        description=(
+            "Tab to open. Required for open_tab; ignored otherwise. One of "
+            "files, browser, vscode, terminal, planner, tasklist."
+        ),
+    )
+
+
+class CanvasUIObservation(Observation):
+    """Acknowledgment that the UI command was dispatched to the frontend."""
+
+
+class CanvasUIExecutor(ToolExecutor[CanvasUIAction, CanvasUIObservation]):
+    def __call__(
+        self,
+        action: CanvasUIAction,
+        conversation=None,  # noqa: ARG002
+    ) -> CanvasUIObservation:
+        return CanvasUIObservation.from_text(
+            f"UI command '{action.command}' dispatched to the Agent Canvas frontend."
+        )
+
+
+_CANVAS_UI_DESCRIPTION = """The user is interacting with you inside Agent Canvas — a web UI with a chat panel on the left and a tabbed right-side panel (files, terminal, browser, vscode, planner, tasklist). This tool lets you drive that right-side panel so the user sees what you just produced.
+
+They will NOT see the files you wrote, the terminal output, or the browser
+unless you call this tool to switch the right-side panel to the relevant
+tab. Call this every time you finish work that produces something the user
+should look at — don't rely on them noticing on their own.
+
+When to call (pick the most specific option that matches your last action):
+
+* You wrote or modified a single file (ANY language, ANY size — including
+  small scripts like a hello-world bash file) →
+    command="navigate_to_file", path=<workspace-relative path of that file>
+
+* You generated an HTML page, image, SVG, PDF, markdown report, or other
+  previewable artifact →
+    command="show_preview", path=<that file>
+
+* You finished editing multiple files in one logical step →
+    command="open_tab", tab="files"
+    (The Files tab automatically renders a diff view when the workspace has
+    uncommitted git changes, which covers the "highlight changes" case.)
+
+* You ran a long-running terminal command, or one whose output the user
+  should inspect →
+    command="open_tab", tab="terminal"
+
+* You browsed to a URL the user should see →
+    First call browser_get_state(include_screenshot=true) after your final
+    browser interaction so Agent Canvas has a screenshot to display, then call
+    command="open_tab", tab="browser"
+    (browser_navigate alone only updates the URL; without browser_get_state,
+    the Browser tab will open without a screenshot.)
+
+Call this BEFORE writing your chat-message summary of the change, so the
+artifact is visible while the user reads what you did. One canvas_ui call
+per logical step is enough — don't repeat it for the same file or tab in
+the same turn."""
+
+
+class CanvasUITool(ToolDefinition[CanvasUIAction, CanvasUIObservation]):
+    """Tool for controlling the Agent Canvas UI from the agent."""
+
+    @classmethod
+    def create(
+        cls,
+        conv_state=None,  # noqa: ARG003
+        **params,  # noqa: ARG003
+    ) -> Sequence["CanvasUITool"]:
+        return [
+            cls(
+                description=_CANVAS_UI_DESCRIPTION,
+                action_type=CanvasUIAction,
+                observation_type=CanvasUIObservation,
+                executor=CanvasUIExecutor(),
+                annotations=ToolAnnotations(
+                    readOnlyHint=True,
+                    destructiveHint=False,
+                    idempotentHint=True,
+                    openWorldHint=False,
+                ),
+            )
+        ]
+
+
+# Persisted pre-client_tools conversations import this module by qualname before
+# restoring their agent and events. Keep the registration until those records
+# have a server-side migration path.
+register_tool("canvas_ui", CanvasUITool)
+
+
+# openhands-automation >= 1.9.0 preset entrypoints build their agent with
+# get_default_agent(finish_tool_response_schema=TaskOutcome). That registers the
+# SDK's builtin FinishTool only inside the entrypoint's own process and
+# advertises it to the agent-server as `openhands.sdk.tool.builtins.finish` — a
+# module that does not self-register — so the remote conversation every Agent
+# Canvas automation run dispatches fails with "ToolDefinition 'FinishTool' is
+# not registered". Registering the plain builtin here is enough: resolve_tool()
+# strips `response_schema` before FinishTool.create() and re-applies it. Drop
+# this once the SDK registers its builtins for remote conversations.
+if FinishTool.__name__ not in list_registered_tools():
+    register_tool(FinishTool.__name__, FinishTool)

tsconfig.json

@@ -0,0 +1,36 @@
+{
+  "include": [
+    "**/*.ts",
+    "**/*.tsx",
+    "**/.server/**/*.ts",
+    "**/.server/**/*.tsx",
+    "**/.client/**/*.ts",
+    "**/.client/**/*.tsx",
+    ".react-router/types/**/*"
+  ],
+  "compilerOptions": {
+    "lib": ["dom", "dom.iterable", "es2022"],
+    "target": "es2022",
+    "types": ["@react-router/node", "vite/client"],
+    "rootDirs": [".", "./.react-router/types"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "noFallthroughCasesInSwitch": true,
+    "ignoreDeprecations": "6.0",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "baseUrl": ".",
+    "paths": {
+      "#/*": ["./src/*"]
+    },
+    // Vite takes care of building everything, not tsc.
+    "noEmit": true
+  }
+}

tsconfig.lib.json

@@ -0,0 +1,34 @@
+{
+  "extends": "./tsconfig.json",
+  "include": [
+    "src/index.ts",
+    "src/**/*.d.ts",
+    "src/lib/**/*.ts",
+    "src/lib/**/*.tsx",
+    "src/components/**/*.ts",
+    "src/components/**/*.tsx",
+    "src/query-client-config.ts",
+    "src/i18n/**/*.ts",
+    "src/i18n/**/*.tsx",
+    "src/routes/conversation.tsx",
+    "src/routes/app-settings.tsx",
+    "src/routes/llm-settings.tsx",
+    "src/routes/mcp-settings.tsx",
+    "src/routes/secrets-settings.tsx"
+  ],
+  "exclude": ["src/**/*.test.ts", "src/**/*.test.tsx"],
+  "compilerOptions": {
+    "noEmit": false,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "declarationMap": false,
+    "outDir": "dist",
+    "rootDir": "src",
+    "types": [
+      "@react-router/node",
+      "vite/client",
+      "vite-plugin-svgr/client",
+      "node"
+    ]
+  }
+}

vercel.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "installCommand": "bash scripts/vercel-install.sh"
+}

vite-env.d.ts

@@ -0,0 +1,8 @@
+/// <reference types="vite/client" />
+
+/**
+ * Absolute filesystem path to the bundled extensions skills directory,
+ * injected by Vite at build time via `define` in vite.config.ts.
+ * Empty string in library builds; always a real path in app/dev builds.
+ */
+declare const __EXTENSIONS_SKILLS_DIR__: string;

vite.config.ts

@@ -0,0 +1,497 @@
+/// <reference types="vitest" />
+/// <reference types="vite-plugin-svgr/client" />
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+import { readFile } from "node:fs/promises";
+import { resolve, dirname, relative, isAbsolute } from "node:path";
+import { defineConfig, loadEnv } from "vite";
+import svgr from "vite-plugin-svgr";
+import { reactRouter } from "@react-router/dev/vite";
+import { configDefaults } from "vitest/config";
+import tailwindcss from "@tailwindcss/vite";
+import prefixer from "postcss-prefix-selector";
+import {
+  AGENT_SERVER_UI_SCOPE_SELECTOR,
+  transformAgentServerUISelector,
+} from "./src/styles/agent-server-ui-style-scope";
+
+const LIB_ENTRY = fileURLToPath(new URL("./src/index.ts", import.meta.url));
+const LIB_EXTERNALS = [
+  "react",
+  "react-dom",
+  "react/jsx-runtime",
+  "react/jsx-dev-runtime",
+  "react-router",
+];
+const APP_CHUNK_MAX_BYTES = 450 * 1024;
+
+const normalizeBasePath = (value?: string) => {
+  const raw = value?.trim();
+  if (!raw || raw === "/") return "/";
+
+  const withLeadingSlash = raw.startsWith("/") ? raw : `/${raw}`;
+  return `${withLeadingSlash.replace(/\/+$/, "")}/`;
+};
+
+// Absolute path to the bundled extensions skills directory in node_modules.
+// Injected as __EXTENSIONS_SKILLS_DIR__ so agent-server-adapter.ts can pass
+// real filesystem paths to the Python agent-server (which uses them to
+// resolve bundled skill resources like scripts/ and references/).
+const _require = createRequire(import.meta.url);
+const EXTENSIONS_SKILLS_DIR = resolve(
+  dirname(_require.resolve("@openhands/extensions/package.json")),
+  "skills",
+);
+const PUBLIC_LOCALES_DIR = resolve(process.cwd(), "public", "locales");
+
+const appBuildConfig = {
+  rolldownOptions: {
+    output: {
+      codeSplitting: {
+        groups: [
+          {
+            // Keep the styling core (HeroUI + tailwind-variants + its
+            // tailwind-merge/clsx deps) in one un-size-split chunk. When the
+            // generic size-split vendor group slices these apart, a HeroUI
+            // component's top-level `tv()` recipe can evaluate before
+            // tailwind-variants' core is initialized, throwing
+            // "TypeError: s is not a function" at module load and blanking the
+            // whole app (root-layout module fails to load → reload loop).
+            name: "vendor-styling",
+            test: /node_modules[\\/](@heroui[\\/]|tailwind-variants[\\/]|tailwind-merge[\\/]|clsx[\\/])/,
+          },
+          {
+            // Keep the markdown / syntax-highlight ecosystem
+            // (react-syntax-highlighter + refractor/lowlight/highlight.js and
+            // the unified/hast/mdast/micromark/vfile module tree it pulls in)
+            // in one un-size-split chunk. Same failure mode as vendor-styling
+            // above: once the file-viewer (HighlightedSourceView) is imported
+            // from a second route, the generic size-split vendor group slices
+            // this tree across chunk boundaries, so a vfile/unified module's
+            // interop `require` shim can evaluate before the chunk that defines
+            // it, throwing "TypeError: i is not a function" at module load and
+            // blanking the whole app (the shared home/conversation/files-tab
+            // chunk fails to load → route-module reload loop).
+            name: "vendor-markdown",
+            test: /node_modules[\\/](react-syntax-highlighter[\\/]|refractor[\\/]|lowlight[\\/]|highlight\.js[\\/]|hastscript[\\/]|(hast|mdast|unist|micromark|remark|rehype)[^\\/]*[\\/]|unified[\\/]|vfile[^\\/]*[\\/]|property-information[\\/]|(comma|space)-separated-tokens[\\/]|character-entities[^\\/]*[\\/]|(parse|stringify)-entities[\\/]|decode-named-character-reference[\\/]|bail[\\/]|trough[\\/]|is-plain-obj[\\/]|zwitch[\\/]|longest-streak[\\/]|ccount[\\/]|escape-string-regexp[\\/]|markdown-table[\\/]|devlop[\\/])/,
+          },
+          {
+            name: "vendor",
+            test: /node_modules[\\/]/,
+            maxSize: APP_CHUNK_MAX_BYTES,
+            minSize: 20 * 1024,
+            entriesAware: true,
+          },
+        ],
+      },
+    },
+  },
+};
+
+export default defineConfig(({ mode }) => {
+  const {
+    VITE_BACKEND_HOST = "127.0.0.1:8000",
+    VITE_USE_TLS = "false",
+    VITE_FRONTEND_PORT = "3001",
+    VITE_INSECURE_SKIP_VERIFY = "false",
+    VITE_BASE_PATH,
+    VITE_VSCODE_BASE_PATH,
+    VITE_VSCODE_TARGET,
+    // Runtime-services metadata for the dev server, passed by launchers that
+    // run the Vite dev server directly (e.g. dev:minimal). Unlike
+    // ingress/static-server, the Vite proxy cannot post-process the upstream
+    // /server_info response, so the launcher serializes the info here and the
+    // middleware below merges it into the proxied response.
+    VITE_RUNTIME_SERVICES_INFO,
+  } = loadEnv(mode, process.cwd());
+
+  const isLibraryBuild = process.env.BUILD_LIB === "true";
+  const USE_TLS = VITE_USE_TLS === "true";
+  const INSECURE_SKIP_VERIFY = VITE_INSECURE_SKIP_VERIFY === "true";
+  const PROTOCOL = USE_TLS ? "https" : "http";
+  const WS_PROTOCOL = USE_TLS ? "wss" : "ws";
+
+  const API_URL = `${PROTOCOL}://${VITE_BACKEND_HOST}/`;
+  const WS_URL = `${WS_PROTOCOL}://${VITE_BACKEND_HOST}/`;
+  const FE_PORT = Number.parseInt(VITE_FRONTEND_PORT, 10);
+  const base = normalizeBasePath(VITE_BASE_PATH);
+
+  return {
+    base,
+    define: {
+      // Empty string for library builds so consumers aren't bound to this
+      // machine's node_modules path; agent-server-adapter falls back to
+      // "public" when the value is falsy.
+      __EXTENSIONS_SKILLS_DIR__: JSON.stringify(
+        isLibraryBuild ? "" : EXTENSIONS_SKILLS_DIR,
+      ),
+    },
+    plugins: [
+      {
+        name: "suppress-chrome-devtools-well-known",
+        apply: "serve",
+        configureServer(server) {
+          server.middlewares.use(
+            "/.well-known/appspecific/com.chrome.devtools.json",
+            (_req, res) => {
+              res.writeHead(204);
+              res.end();
+            },
+          );
+        },
+      },
+      {
+        name: "serve-generated-i18n-locales",
+        apply: "serve",
+        configureServer(server) {
+          server.middlewares.use(async (req, res, next) => {
+            const method = req.method ?? "GET";
+            if (method !== "GET" && method !== "HEAD") {
+              next();
+              return;
+            }
+
+            const pathname = new URL(req.url ?? "", "http://localhost")
+              .pathname;
+            if (
+              !pathname.startsWith("/locales/") ||
+              !pathname.endsWith(".json")
+            ) {
+              next();
+              return;
+            }
+
+            const requestedPath = decodeURIComponent(
+              pathname.slice("/locales/".length),
+            );
+            const filePath = resolve(PUBLIC_LOCALES_DIR, requestedPath);
+            const relativePath = relative(PUBLIC_LOCALES_DIR, filePath);
+            if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
+              res.writeHead(403);
+              res.end();
+              return;
+            }
+
+            try {
+              const content = await readFile(filePath);
+              res.writeHead(200, {
+                "Content-Type": "application/json; charset=utf-8",
+                "Cache-Control": "no-cache",
+              });
+              res.end(method === "HEAD" ? "" : content);
+            } catch {
+              next();
+            }
+          });
+        },
+      },
+      !process.env.VITEST && !isLibraryBuild && reactRouter(),
+      svgr(),
+      tailwindcss(),
+    ],
+    resolve: {
+      tsconfigPaths: true,
+    },
+    css: {
+      postcss: {
+        plugins: [
+          prefixer({
+            prefix: AGENT_SERVER_UI_SCOPE_SELECTOR,
+            transform(
+              prefix: string,
+              selector: string,
+              prefixedSelector: string,
+            ) {
+              return transformAgentServerUISelector(
+                prefix,
+                selector,
+                prefixedSelector,
+              );
+            },
+          }),
+        ],
+      },
+    },
+    build: isLibraryBuild
+      ? {
+          outDir: "dist",
+          emptyOutDir: true,
+          sourcemap: true,
+          lib: {
+            entry: LIB_ENTRY,
+            formats: ["es"],
+          },
+          rollupOptions: {
+            external: LIB_EXTERNALS,
+            output: [
+              {
+                format: "es",
+                preserveModules: true,
+                preserveModulesRoot: "src",
+                entryFileNames: "[name].js",
+                chunkFileNames: "chunks/[name]-[hash].js",
+                assetFileNames: "assets/[name]-[hash][extname]",
+              },
+              {
+                format: "cjs",
+                preserveModules: true,
+                preserveModulesRoot: "src",
+                entryFileNames: "[name].cjs",
+                chunkFileNames: "chunks/[name]-[hash].cjs",
+                assetFileNames: "assets/[name]-[hash][extname]",
+                exports: "named",
+              },
+            ],
+          },
+        }
+      : appBuildConfig,
+    copyPublicDir: !isLibraryBuild,
+    optimizeDeps: {
+      // Disable discovery of new deps at runtime. All deps must be listed in
+      // `include`. This prevents Vite from returning 504s while optimizing
+      // newly-discovered deps - Safari doesn't retry like Chrome does.
+      noDiscovery: true,
+      include: [
+        // Pre-bundle client entry dependencies so the first page load does not 504
+        // with Vite's "Outdated Optimize Dep" before hydration finishes.
+        // Safari is particularly sensitive to runtime dep optimization - it gets
+        // stuck in 504 errors when Vite triggers "optimized dependencies changed. reloading"
+        "react",
+        "react/jsx-runtime",
+        "react-dom/client",
+        "react-router/dom",
+        // Pre-bundle ALL dependencies to prevent runtime optimization and page reloads
+        // These are discovered during initial app load:
+        "posthog-js",
+        "@tanstack/react-query",
+        "react-hot-toast",
+        "i18next",
+        "i18next-http-backend",
+        "i18next-browser-languagedetector",
+        "react-i18next",
+        "axios",
+        "@uidotdev/usehooks",
+        "react-icons/fa6",
+        "react-icons/fa",
+        "clsx",
+        "tailwind-merge",
+        // CJS dependencies used by react-transition-group. Without pre-bundling,
+        // Vite can serve them directly to the browser before route hydration.
+        "prop-types",
+        "react-is",
+        "@heroui/react",
+        "lucide-react",
+        "@microlink/react-json-view",
+        "socket.io-client",
+        // These are discovered when launching conversations:
+        "react-icons/vsc",
+        "react-icons/lu",
+        "react-icons/di",
+        "react-icons/io5",
+        "react-icons/io",
+        "@monaco-editor/react",
+        "react-textarea-autosize",
+        "react-markdown",
+        "remark-gfm",
+        "remark-breaks",
+        "react-syntax-highlighter",
+        "react-syntax-highlighter/dist/esm/styles/prism",
+        "react-syntax-highlighter/dist/esm/styles/hljs",
+        // Terminal dependencies - added to prevent runtime optimization
+        "@xterm/addon-fit",
+        "@xterm/xterm",
+        "@xterm/xterm/css/xterm.css",
+        // OpenHands typescript client
+        "@openhands/typescript-client",
+        "@openhands/typescript-client/client/http-client",
+        "@openhands/typescript-client/client/device-flow-client",
+        "@openhands/typescript-client/clients",
+        "@openhands/typescript-client/events/remote-events-list",
+        "@openhands/typescript-client/workspace/remote-workspace",
+        // Additional dependencies discovered at runtime
+        "class-variance-authority",
+        "downshift",
+        "framer-motion",
+        "rehype-raw",
+        "rehype-sanitize",
+        // ``shell-quote`` is a CJS module used by ``src/utils/acp-command.ts``
+        // for the Settings → Agent textarea. With ``noDiscovery: true`` above,
+        // omitting it from this list means Vite serves the raw CJS file to
+        // the browser and dev crashes with ``ReferenceError: exports is not
+        // defined`` on the first import of agent-settings.tsx.
+        "shell-quote",
+        "unist-util-visit",
+        "uuid",
+        "zustand",
+        "zustand/middleware",
+        // Syntax highlighter language definitions - Safari fails if these are
+        // optimized at runtime. Include all commonly used languages.
+        "react-syntax-highlighter/dist/esm/languages/prism/bash",
+        "react-syntax-highlighter/dist/esm/languages/prism/batch",
+        "react-syntax-highlighter/dist/esm/languages/prism/c",
+        "react-syntax-highlighter/dist/esm/languages/prism/clike",
+        "react-syntax-highlighter/dist/esm/languages/prism/clojure",
+        "react-syntax-highlighter/dist/esm/languages/prism/cpp",
+        "react-syntax-highlighter/dist/esm/languages/prism/csharp",
+        "react-syntax-highlighter/dist/esm/languages/prism/css",
+        "react-syntax-highlighter/dist/esm/languages/prism/dart",
+        "react-syntax-highlighter/dist/esm/languages/prism/diff",
+        "react-syntax-highlighter/dist/esm/languages/prism/docker",
+        "react-syntax-highlighter/dist/esm/languages/prism/elixir",
+        "react-syntax-highlighter/dist/esm/languages/prism/erlang",
+        "react-syntax-highlighter/dist/esm/languages/prism/fsharp",
+        "react-syntax-highlighter/dist/esm/languages/prism/go",
+        "react-syntax-highlighter/dist/esm/languages/prism/graphql",
+        "react-syntax-highlighter/dist/esm/languages/prism/groovy",
+        "react-syntax-highlighter/dist/esm/languages/prism/haskell",
+        "react-syntax-highlighter/dist/esm/languages/prism/hcl",
+        "react-syntax-highlighter/dist/esm/languages/prism/http",
+        "react-syntax-highlighter/dist/esm/languages/prism/ini",
+        "react-syntax-highlighter/dist/esm/languages/prism/java",
+        "react-syntax-highlighter/dist/esm/languages/prism/javascript",
+        "react-syntax-highlighter/dist/esm/languages/prism/json",
+        "react-syntax-highlighter/dist/esm/languages/prism/json5",
+        "react-syntax-highlighter/dist/esm/languages/prism/jsx",
+        "react-syntax-highlighter/dist/esm/languages/prism/julia",
+        "react-syntax-highlighter/dist/esm/languages/prism/kotlin",
+        "react-syntax-highlighter/dist/esm/languages/prism/less",
+        "react-syntax-highlighter/dist/esm/languages/prism/lua",
+        "react-syntax-highlighter/dist/esm/languages/prism/makefile",
+        "react-syntax-highlighter/dist/esm/languages/prism/markdown",
+        "react-syntax-highlighter/dist/esm/languages/prism/markup",
+        "react-syntax-highlighter/dist/esm/languages/prism/matlab",
+        "react-syntax-highlighter/dist/esm/languages/prism/nginx",
+        "react-syntax-highlighter/dist/esm/languages/prism/nix",
+        "react-syntax-highlighter/dist/esm/languages/prism/objectivec",
+        "react-syntax-highlighter/dist/esm/languages/prism/ocaml",
+        "react-syntax-highlighter/dist/esm/languages/prism/perl",
+        "react-syntax-highlighter/dist/esm/languages/prism/php",
+        "react-syntax-highlighter/dist/esm/languages/prism/powershell",
+        "react-syntax-highlighter/dist/esm/languages/prism/properties",
+        "react-syntax-highlighter/dist/esm/languages/prism/protobuf",
+        "react-syntax-highlighter/dist/esm/languages/prism/python",
+        "react-syntax-highlighter/dist/esm/languages/prism/r",
+        "react-syntax-highlighter/dist/esm/languages/prism/regex",
+        "react-syntax-highlighter/dist/esm/languages/prism/ruby",
+        "react-syntax-highlighter/dist/esm/languages/prism/rust",
+        "react-syntax-highlighter/dist/esm/languages/prism/sass",
+        "react-syntax-highlighter/dist/esm/languages/prism/scala",
+        "react-syntax-highlighter/dist/esm/languages/prism/scss",
+        "react-syntax-highlighter/dist/esm/languages/prism/shell-session",
+        "react-syntax-highlighter/dist/esm/languages/prism/solidity",
+        "react-syntax-highlighter/dist/esm/languages/prism/sql",
+        "react-syntax-highlighter/dist/esm/languages/prism/swift",
+        "react-syntax-highlighter/dist/esm/languages/prism/toml",
+        "react-syntax-highlighter/dist/esm/languages/prism/tsx",
+        "react-syntax-highlighter/dist/esm/languages/prism/typescript",
+        "react-syntax-highlighter/dist/esm/languages/prism/yaml",
+      ],
+    },
+    server: {
+      port: FE_PORT,
+      strictPort: true, // Fail if port is busy (dynamic allocation handles fallback)
+      host: true,
+      allowedHosts: true,
+      proxy: {
+        "/api": {
+          target: API_URL,
+          changeOrigin: true,
+          secure: !INSECURE_SKIP_VERIFY,
+        },
+        "/server_info": {
+          target: API_URL,
+          changeOrigin: true,
+          secure: !INSECURE_SKIP_VERIFY,
+        },
+        "/alive": {
+          target: API_URL,
+          changeOrigin: true,
+          secure: !INSECURE_SKIP_VERIFY,
+        },
+        "/health": {
+          target: API_URL,
+          changeOrigin: true,
+          secure: !INSECURE_SKIP_VERIFY,
+        },
+        "/ready": {
+          target: API_URL,
+          changeOrigin: true,
+          secure: !INSECURE_SKIP_VERIFY,
+        },
+        "/docs": {
+          target: API_URL,
+          changeOrigin: true,
+          secure: !INSECURE_SKIP_VERIFY,
+        },
+        "/redoc": {
+          target: API_URL,
+          changeOrigin: true,
+          secure: !INSECURE_SKIP_VERIFY,
+        },
+        "/openapi.json": {
+          target: API_URL,
+          changeOrigin: true,
+          secure: !INSECURE_SKIP_VERIFY,
+        },
+        "/sockets": {
+          target: WS_URL,
+          ws: true,
+          changeOrigin: true,
+          secure: !INSECURE_SKIP_VERIFY,
+        },
+        // The bundled editor, when the launcher put agent-server into
+        // prefix-mode (`dev:minimal` — see VITE_VSCODE_TARGET in
+        // scripts/dev-safe.mjs). agent-server then advertises
+        // `<origin><prefix>/?tkn=…`, and this origin is Vite's, so without
+        // this entry the prefix falls through to the SPA and the editor
+        // button opens a second copy of the canvas.
+        //
+        // The prefix is preserved, not rewritten: openvscode-server is
+        // launched with `--server-base-path`, generates its HTTP and
+        // WebSocket URLs beneath the prefix, and only answers there.
+        // `ws: true` because the workbench upgrades to a WebSocket
+        // immediately on load.
+        ...(VITE_VSCODE_BASE_PATH && VITE_VSCODE_TARGET
+          ? {
+              [VITE_VSCODE_BASE_PATH]: {
+                target: VITE_VSCODE_TARGET,
+                ws: true,
+                changeOrigin: true,
+                secure: !INSECURE_SKIP_VERIFY,
+              },
+            }
+          : {}),
+      },
+      watch: {
+        ignored: ["**/node_modules/**", "**/.git/**"],
+      },
+    },
+    ssr: {
+      noExternal: ["react-syntax-highlighter"],
+    },
+    clearScreen: false,
+    test: {
+      environment: "jsdom",
+      setupFiles: ["vitest.setup.ts"],
+      exclude: [...configDefaults.exclude, "tests"],
+      // The full suite runs many DOM-heavy tests in parallel, which can
+      // push individual `userEvent`-driven tests past Vitest's 5000ms
+      // default on busy machines (the skills-settings and i18n
+      // namespace tests are the typical victims). Bumping the global
+      // timeout keeps these tests deterministic without changing any
+      // production behavior.
+      testTimeout: 30000,
+      hookTimeout: 30000,
+      server: {
+        deps: {
+          inline: ["@openhands/typescript-client"],
+        },
+      },
+      coverage: {
+        reporter: ["text", "json", "html", "lcov", "text-summary"],
+        reportsDirectory: "coverage",
+        include: ["src/**/*.{ts,tsx}"],
+      },
+    },
+  };
+});

vitest.setup.ts

@@ -0,0 +1,222 @@
+import { afterAll, afterEach, beforeAll, beforeEach, vi } from "vitest";
+import { cleanup } from "@testing-library/react";
+import { server } from "#/mocks/node";
+import "@testing-library/jest-dom/vitest";
+
+// Some modules read env at import time before Vitest's per-test hooks run.
+// The beforeEach below restores the same default after tests call
+// `vi.unstubAllEnvs()`.
+vi.stubEnv("VITE_SESSION_API_KEY", "test-session-key");
+
+if (typeof HTMLCanvasElement !== "undefined") {
+  HTMLCanvasElement.prototype.getContext = vi.fn();
+}
+
+if (typeof HTMLElement !== "undefined") {
+  HTMLElement.prototype.scrollTo = vi.fn();
+}
+
+const windowStub =
+  typeof window === "undefined"
+    ? ({ event: undefined } as unknown as Window & typeof globalThis)
+    : window;
+
+vi.stubGlobal("window", windowStub);
+windowStub.scrollTo = vi.fn();
+
+// Node.js 25+ ships a built-in localStorage that requires --localstorage-file
+// and is not functional without it. Stub it with a plain in-memory
+// implementation so zustand's persist middleware works in tests.
+if (
+  typeof localStorage === "undefined" ||
+  typeof localStorage.setItem !== "function"
+) {
+  const store: Record<string, string> = {};
+  vi.stubGlobal("localStorage", {
+    getItem: (key: string) => store[key] ?? null,
+    setItem: (key: string, value: string) => {
+      store[key] = String(value);
+    },
+    removeItem: (key: string) => {
+      delete store[key];
+    },
+    clear: () => {
+      Object.keys(store).forEach((k) => delete store[k]);
+    },
+    get length() {
+      return Object.keys(store).length;
+    },
+    key: (index: number) => Object.keys(store)[index] ?? null,
+  });
+}
+
+if (typeof requestAnimationFrame === "undefined") {
+  vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) =>
+    setTimeout(() => callback(0), 0),
+  );
+  vi.stubGlobal(
+    "cancelAnimationFrame",
+    (timeoutId: ReturnType<typeof setTimeout>) => clearTimeout(timeoutId),
+  );
+}
+
+// MSW's XMLHttpRequest interceptor references the bare `ProgressEvent`
+// global from inside async `respondWith` callbacks (via `createEvent`), and
+// the bare `XMLHttpRequestUpload` global in `trigger` (`target instanceof
+// XMLHttpRequestUpload`). Vitest's jsdom environment installs these as own
+// properties on `globalThis` and removes them during per-file teardown with
+// `keys.forEach((key) => delete global[key])`. If an in-flight intercepted
+// XHR (e.g. PostHog analytics, or any request that escaped to the real
+// network under `onUnhandledRequest: "bypass"` and is still waiting on a
+// socket) settles after teardown, its callback evaluates `ProgressEvent`
+// against a torn-down global and throws
+// `ReferenceError: ProgressEvent is not defined` (or the
+// `XMLHttpRequestUpload` equivalent). Vitest reports that as an
+// unhandled rejection and fails the whole run even though every test passed.
+//
+// Two earlier attempts at this (an own-property getter, then the `afterAll`
+// drain below) both put the fallback where teardown can reach it, or bounded
+// how long a late callback may take. Neither holds: `delete` removes any own
+// property regardless of who defined it, and a request stuck on a real socket
+// can settle long after 30 macrotask ticks.
+//
+// `delete` only removes *own* properties, while identifier resolution walks
+// the prototype chain. So the fallbacks go on an object inserted into
+// `globalThis`'s prototype chain, where teardown cannot delete them: while
+// the environment is alive jsdom's own properties shadow them, and once
+// teardown removes those own properties, the bare identifiers resolve
+// through the prototype to the classes below. Node's `globalThis` does not
+// have `Object.prototype` as its direct prototype, so this adds nothing to
+// plain objects.
+class MockProgressEvent extends Event {
+  readonly lengthComputable: boolean;
+
+  readonly loaded: number;
+
+  readonly total: number;
+
+  constructor(type: string, eventInitDict: ProgressEventInit = {}) {
+    super(type, eventInitDict);
+    this.lengthComputable = eventInitDict.lengthComputable ?? false;
+    this.loaded = eventInitDict.loaded ?? 0;
+    this.total = eventInitDict.total ?? 0;
+  }
+}
+
+// The interceptor only needs `XMLHttpRequestUpload` as an `instanceof`
+// operand. While jsdom is alive its own property shadows this fallback, so
+// behavior is unchanged; after teardown the check just takes the non-upload
+// branch, quietly skipping listener dispatch for callbacks that have already
+// outlived their environment instead of crashing the run.
+class MockXMLHttpRequestUpload extends EventTarget {}
+
+// Setup files run once per test file, and a worker process is reused across
+// files. Without this marker each file would splice another holder into the
+// prototype chain, so the chain would grow with every file in the run.
+const XHR_GLOBALS_FALLBACK = Symbol.for("agent-canvas.xhr-globals-fallback");
+
+function installXhrGlobalsFallback(fallbacks: Record<string, unknown>) {
+  const currentProto = Object.getPrototypeOf(globalThis) as object | null;
+  if (currentProto && XHR_GLOBALS_FALLBACK in currentProto) return;
+
+  const holder = Object.create(currentProto) as Record<PropertyKey, unknown>;
+  Object.defineProperty(holder, XHR_GLOBALS_FALLBACK, { value: true });
+  for (const [name, fallback] of Object.entries(fallbacks)) {
+    Object.defineProperty(holder, name, {
+      value: fallback,
+      configurable: true,
+      writable: true,
+    });
+  }
+  Object.setPrototypeOf(globalThis, holder);
+}
+
+installXhrGlobalsFallback({
+  ProgressEvent: MockProgressEvent,
+  XMLHttpRequestUpload: MockXMLHttpRequestUpload,
+});
+
+// Mock ResizeObserver for test environment
+class MockResizeObserver {
+  observe = vi.fn();
+
+  unobserve = vi.fn();
+
+  disconnect = vi.fn();
+}
+
+// Mock the i18n provider
+vi.mock("react-i18next", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("react-i18next")>()),
+  useTranslation: () => ({
+    t: (key: string) => key,
+    i18n: {
+      language: "en",
+      exists: () => false,
+    },
+  }),
+}));
+
+vi.mock("#/hooks/use-is-on-tos-page", () => ({
+  useIsOnTosPage: () => false,
+}));
+
+vi.mock("#/hooks/use-is-on-intermediate-page", () => ({
+  useIsOnIntermediatePage: () => false,
+}));
+
+// Mock useRevalidator from react-router to allow direct store manipulation in tests
+vi.mock("react-router", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("react-router")>()),
+  useRevalidator: () => ({
+    revalidate: vi.fn(),
+  }),
+}));
+
+// Import the Zustand mock to enable automatic store resets
+vi.mock("zustand");
+
+// Mock requests during tests
+beforeAll(() => {
+  server.listen({ onUnhandledRequest: "bypass" });
+  vi.stubGlobal("ResizeObserver", MockResizeObserver);
+});
+
+beforeEach(() => {
+  vi.stubEnv("VITE_SESSION_API_KEY", "test-session-key");
+});
+
+afterEach(async () => {
+  server.resetHandlers();
+  window.sessionStorage?.removeItem("openhands-active-backend");
+  // Cleanup the document body after each test
+  cleanup();
+  // Drain any queued microtasks before jsdom is torn down between test files.
+  // Without this, async state updates queued during render (for example by
+  // HeroUI v2 components wrapped in framer-motion's LazyMotion) can resolve
+  // after `window` is gone and trigger spurious unhandled rejections in
+  // react-dom's `resolveUpdatePriority`. We use `Promise.resolve()` (a
+  // microtask) rather than `setTimeout(0)` so this stays compatible with
+  // tests that install fake timers.
+  await Promise.resolve();
+  await Promise.resolve();
+});
+afterAll(async () => {
+  // Drain pending MSW `respondWith` callbacks (and any other queued
+  // macrotasks) before jsdom is torn down, so most late callbacks settle
+  // against a live jsdom rather than a torn-down one. This is a best-effort
+  // tidy-up, not the guarantee: a callback can always outlast the drain
+  // window (a bypassed request stuck on a real socket, for instance), which
+  // is what the prototype-chain XHR-globals fallback above is for. We
+  // restore real timers first so a test that left fake timers active can't
+  // stall the drain.
+  vi.useRealTimers();
+  // Reset handlers first so no new intercepted requests start processing
+  // during the drain window.
+  server.resetHandlers();
+  for (let i = 0; i < 30; i += 1) {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  }
+  server.close();
+  vi.unstubAllGlobals();
+});