π OpenHands: AI-Driven Development
docs: remove the unwanted specs directory (#18820)
πΎ smolpaws9508e7246825
diff --git a/.agents/skills/frontend-development/references/guide.md b/.agents/skills/frontend-development/references/guide.mdindex 9730125298..23d53f86fe 100644--- a/.agents/skills/frontend-development/references/guide.md+++ b/.agents/skills/frontend-development/references/guide.md@@ -29,7 +29,7 @@ Bundled catalog skills use the persisted `enabled_skills` allow-list defaulted f## Workspace files-Local Files discovery preferences belong to `misc_settings.app_preferences.workspace_file_discovery`, keyed by working directory on the active backend. `useWorkspaceFileDiscovery` reads the settings cache and saves sparse workspace patches. Preserve default exclusions and the 2,000-file cap when no configuration exists. Fetch one extra result to distinguish truncation from an exact-size list. Cloud keeps its server-side listing contract without these controls. See `specs/workspace-file-discovery.md`.+Local Files discovery preferences belong to `misc_settings.app_preferences.workspace_file_discovery`, keyed by working directory on the active backend. `useWorkspaceFileDiscovery` reads the settings cache and saves sparse workspace patches. Preserve default exclusions and the 2,000-file cap when no configuration exists. Fetch one extra result to distinguish truncation from an exact-size list. Cloud keeps its server-side listing contract without these controls.## Caret appearance contracts@@ -134,7 +134,7 @@ When adding code that needs a new string, decide up front which rule it falls un- Theme/customization tokens for the embedded shell are exposed as `--oh-*` CSS variables. Override them through `styleOverrides`, `style`, or host CSS targeting `[data-agent-server-ui]`; Tailwind theme tokens in `src/tailwind.css` should continue to reference those variables with `@theme inline` so host apps can restyle the UI without reworking component class names.- Small form feedback uses the `feedback-error` / `feedback-success` text roles (`--oh-feedback-error` / `--oh-feedback-success`), separately from the general danger/success control palette. Their built-in values must meet 4.5:1 on modal surfaces; host overrides remain owned by the embedding root. See `src/themes/README.md` and the theme contrast tests when migrating raw feedback colors.- Regression coverage for the CSS isolation work lives in `__tests__/agent-server-ui-providers.test.tsx`, `__tests__/agent-server-ui-style-scope.test.ts`, and the browser-level CSS-isolation test in `tests/e2e/mock-llm/regressions/mock-llm-ui-regressions.spec.ts`.-- MCP credential selection: `SaveAsSecretToggle` keeps its native checkbox as the semantic control and uses `ToggleSwitchVisual` for the decorative track. Selection uses contrast/surface tokens. Keep both states' labels readable, allow long secret names to wrap with their help control, and preserve visible keyboard focus. See `specs/mcp-secret-selection.md` (MCP-005).+- MCP credential selection: `SaveAsSecretToggle` keeps its native checkbox as the semantic control and uses `ToggleSwitchVisual` for the decorative track. Selection uses contrast/surface tokens. Keep both states' labels readable, allow long secret names to wrap with their help control, and preserve visible keyboard focus.- Conversation history is loaded lazily, REST-first then WebSocket:- `useConversationHistory` (in `src/hooks/query/use-conversation-history.ts`) fetches only the most recent `INITIAL_HISTORY_PAGE_SIZE` (default 50) events using `sort_order='TIMESTAMP_DESC'`, then reverses to chronological order. Older pages are paginated in via `useLoadOlderEvents` when the user scrolls near the top of the chat.@@ -161,7 +161,7 @@ When adding code that needs a new string, decide up front which rule it falls un- `ManageWorkspacesModal` should require a confirmation step before removing either a saved workspace or a workspace parent; parent removals should mention the child-workspace impact, and tests should assert both the confirmation flow and that removing the selected workspace clears the launch selection.- In `useWorkspacesStore`, keep `clearWorkspaces()` scoped to literal workspaces only; use explicit helpers like `clearWorkspaceParents()` / `clearAll()` for broader resets so future callers do not accidentally wipe parent registrations.-- Default LLM model β `DEFAULT_SETTINGS.llm_model` (`"openhands/glm-5.2"`, defined in `src/services/settings.ts`) is the canonical frontend default. `buildConfiguredOpenHandsAgentSettings` in `src/api/agent-server-adapter.ts` **always** sends this value explicitly when the resolved `llm.model` is absent, empty, or whitespace-only β the frontend never relies on the agent-server SDK's own default (`gpt-5.5`). If you change the default model, update `DEFAULT_SETTINGS.llm_model` in `src/services/settings.ts` **and** the checklist in `specs/llm-defaults.md`. Spec: `@spec LLD-001`.+- Default LLM model β `DEFAULT_SETTINGS.llm_model` (`"openhands/glm-5.2"`, defined in `src/services/settings.ts`) is the canonical frontend default. `buildConfiguredOpenHandsAgentSettings` in `src/api/agent-server-adapter.ts` **always** sends this value explicitly when the resolved `llm.model` is absent, empty, or whitespace-only β the frontend never relies on the agent-server SDK's own default (`gpt-5.5`). If you change the default model, update `DEFAULT_SETTINGS.llm_model` in `src/services/settings.ts`.- Custom secrets are NOT auto-attached by the agent-server. `POST /api/conversations` only persists what the client sends in `request.secrets`; the persisted secrets store (`/api/settings/secrets`) is never read at conversation start. `buildStartConversationRequestWithEncryptedSettings` enumerates `SecretsService.getSecrets()` and turns each entry into a `LookupSecret` whose `url` points back at `/api/settings/secrets/{name}` and whose `headers` carry `X-Session-API-Key` for auth.diff --git a/.agents/skills/local-stack-runtime/SKILL.md b/.agents/skills/local-stack-runtime/SKILL.mdindex d1720e1b45..8f8b4574db 100644--- a/.agents/skills/local-stack-runtime/SKILL.md+++ b/.agents/skills/local-stack-runtime/SKILL.md@@ -18,4 +18,4 @@ Maintain the shared configuration and launch plumbing across Vite/static develop## Reference-- **`references/guide.md`** β Runtime-services schema and prompt plumbing, launcher environment variables, ingress routes, version synchronization, security, Docker build architecture, README synchronization, and spec-tag conventions.+- **`references/guide.md`** β Runtime-services schema and prompt plumbing, launcher environment variables, ingress routes, version synchronization, security, Docker build architecture, and README synchronization.diff --git a/.agents/skills/local-stack-runtime/references/guide.md b/.agents/skills/local-stack-runtime/references/guide.mdindex ee9950ac29..0ff6d95dbd 100644--- a/.agents/skills/local-stack-runtime/references/guide.md+++ b/.agents/skills/local-stack-runtime/references/guide.md@@ -124,5 +124,3 @@ you are running inside of β NOT the automation backend.- Dockerfile ARG defaults are kept as fallbacks for local `docker build` without the CI workflow; CI always passes `--build-arg` overrides from the JSON.- To bump a version, edit `config/defaults.json` only β the JS scripts, Docker build, and CI workflow all derive their values from it.- Docker all-in-one image: `.github/workflows/docker.yml` builds and publishes `ghcr.io/openhands/agent-canvas` β a combined image that bundles the agent-server (from `ghcr.io/openhands/agent-server`), the automation server (`openhands-automation` via pip), and the agent-canvas frontend (static build). The Dockerfile lives at `docker/Dockerfile`, the entrypoint at `docker/entrypoint.sh`. The workflow structure mirrors the SDK repo's `server.yml`: a `build-and-push-image` matrix job (2 Γ arch: amd64 on `ubuntu-24.04`, arm64 on `ubuntu-24.04-arm`) pushes arch-suffixed tags, then `merge-manifests` creates multi-arch manifests via `docker buildx imagetools create`, then `consolidate-build-info` aggregates artifacts, and `update-pr-description` updates the PR body (using `<!-- AGENT_CANVAS_DOCKER_START -->` / `<!-- AGENT_CANVAS_DOCKER_END -->` markers). The workflow triggers on push to main, `v*` tags (releases), PRs, and `workflow_dispatch`. On release tags it also pushes semver tags (e.g. `1.2.3`, `1.2`, `1`, `latest`). Fork PRs are skipped (no GHCR auth). On PRs that link an `OpenHands/software-agent-sdk` PR in the description, the Docker workflow uses that SDK PR's published branch image (`ghcr.io/openhands/agent-server:<branch-with-slashes-as-dashes>-python`) as the agent-server base image unless a `workflow_dispatch` input explicitly overrides it. The image exposes port 8000 as a unified entry point: `/api/automation/*` β automation (:18001), `/api/*` β agent-server (:18000), `/*` β static frontend. The Dockerfile accepts the public `VITE_POSTHOG_API_KEY` build arg; CI passes staging for PR/main images and production for tagged releases. The npm release workflow passes the same production key to both the app and library builds. The entrypoint auto-generates **both** the session API key and `OH_SECRET_KEY` (persisted to `~/.openhands/agent-canvas/session-api-key.txt` and `secret-key.txt` respectively) when none is provided, so the image runs secure by default. Users can override either via env var (`OH_SECRET_KEY`, `SESSION_API_KEY` / `OH_SESSION_API_KEYS_0`). `scripts/dev-safe.mjs` uses the same `secret-key.txt` file, so dev mode and Docker share the same key when both use the same `~/.openhands` directory.--- Spec files live under `specs/`. Spec IDs are stable β never renumber. Mark deprecated specs with ~~strikethrough~~. Tag implementation code and tests with `// @spec BM-002 β Short title` comments so specs are grep-able across the codebase (`grep -rn '@spec BM-' src/ __tests__/`). Place the comment on the line immediately above the relevant code block or test. When multiple tests cover the same spec, use `it.each` if the test structure is identical.diff --git a/.agents/skills/verify-openhands/references/feature-map/F25-backends-and-cloud.md b/.agents/skills/verify-openhands/references/feature-map/F25-backends-and-cloud.mdindex 32cffee49b..6801110e9b 100644--- a/.agents/skills/verify-openhands/references/feature-map/F25-backends-and-cloud.md+++ b/.agents/skills/verify-openhands/references/feature-map/F25-backends-and-cloud.md@@ -17,7 +17,7 @@ token and turns a Managed Agents session into a backend.Everything except the Cloud and DigitalOcean accounts themselves can be drivenlocally with a second `control-openhands` stack as the extra backend.-Source: `src/components/features/backends/`, `src/contexts/active-backend-context.tsx`, `src/api/backend-registry/`, `src/hooks/query/use-backends-health.ts`, `src/routes/device-verify.tsx`, `src/routes/shared-conversation.tsx`, `src/components/features/conversation/conversation-name-context-menu.tsx`, `src/api/cloud/`, `src/api/mars/`, `src/hooks/use-mars-*.ts`, `src/hooks/use-connect-mars-session.ts`, `src/hooks/use-launch-mars-session.ts`, `src/hooks/query/use-mars-agents.ts`, `src/components/features/sidebar/mars-session-panel.tsx`, `src/assets/branding/digitalocean-logo.svg`, `scripts/mars-web-bridge.mjs`, `scripts/mars-tunnel-bridge.mjs`, `specs/backend-management.md`.+Source: `src/components/features/backends/`, `src/contexts/active-backend-context.tsx`, `src/api/backend-registry/`, `src/hooks/query/use-backends-health.ts`, `src/routes/device-verify.tsx`, `src/routes/shared-conversation.tsx`, `src/components/features/conversation/conversation-name-context-menu.tsx`, `src/api/cloud/`, `src/api/mars/`, `src/hooks/use-mars-*.ts`, `src/hooks/use-connect-mars-session.ts`, `src/hooks/use-launch-mars-session.ts`, `src/hooks/query/use-mars-agents.ts`, `src/components/features/sidebar/mars-session-panel.tsx`, `src/assets/branding/digitalocean-logo.svg`, `scripts/mars-web-bridge.mjs`, `scripts/mars-tunnel-bridge.mjs`.## Sub-featuresdiff --git a/.agents/skills/verify-openhands/references/mapping.md b/.agents/skills/verify-openhands/references/mapping.mdindex 3f5a80a49c..66ba7c0c44 100644--- a/.agents/skills/verify-openhands/references/mapping.md+++ b/.agents/skills/verify-openhands/references/mapping.md@@ -47,7 +47,7 @@ candidate. Sources, roughly in order of yield:6. **Backends and modes**: local vs Cloud backend, public vs local auth, ACPagents, partial stacks (`agent-canvas --help`), Electron, Docker, and theembeddable library (`src/index.ts` / `build:lib`).-7. **Docs, specs and tests**: `README.md`, `docs/*.md`, `specs/*.md` describe+7. **Docs and tests**: `README.md`, `docs/*.md` describeintended behavior. The Playwright suites under `tests/e2e/` (mock-LLM, live,bind-policy, live-acp) assert behaviors a user sees too: read them forselectors and for behaviors the map lacks, then map those behaviors asdiff --git a/AGENTS.md b/AGENTS.mdindex 119dce3b9b..6622369d24 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -86,10 +86,8 @@ Create TDD tests for behavioral changes. Keep tests focused on user behavior andUse the `e2e-testing` skill for suite selection and E2E-specific requirements.-## Specifications and Releases+## Releases-- Spec files live under `specs/`. Keep spec IDs stable and mark deprecated specs with strikethrough rather than renumbering them.-- Tag implementation code and tests with `// @spec BM-002 β Short title` comments immediately above the relevant block so coverage remains grep-able.- Follow `.agents/skills/release.md` for release automation. Never hand-edit a release-please branch.## DigitalOcean Managed Agentsdiff --git a/docs/CANVAS_EXTENSIONS_TESTING.md b/docs/CANVAS_EXTENSIONS_TESTING.mdindex 8f9030f19e..06b45c5c3d 100644--- a/docs/CANVAS_EXTENSIONS_TESTING.md+++ b/docs/CANVAS_EXTENSIONS_TESTING.md@@ -89,6 +89,3 @@ contract lands. That test must additionally verify:- persistence across Agent Server and browser restarts;- session-authenticated bundle delivery;- isolation when switching between active backends.--The backend contract and acceptance criteria are documented in-[`specs/canvas-extensions.md`](../specs/canvas-extensions.md).diff --git a/specs/backend-management.md b/specs/backend-management.mddeleted file mode 100644index 8c18705ea5..0000000000--- a/specs/backend-management.md+++ /dev/null@@ -1,15 +0,0 @@-# 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.--### BM-004: Theme-aware connection feedback-- [x] Connection errors, disabled-backend diagnostics, and connected/disconnected status text shall use the host-overridable feedback roles in all five themes. Small feedback text shall remain readable on its actual surface, including tinted error panels.diff --git a/specs/canvas-extensions.md b/specs/canvas-extensions.mddeleted file mode 100644index 145b9e46ed..0000000000--- a/specs/canvas-extensions.md+++ /dev/null@@ -1,321 +0,0 @@-# 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 UI calls Canvas Extensions **Apps**: the inventory item is-**Customize > Apps** at `/apps`, installed with **Add app**; "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 > Apps 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- app card's **Update** action re-installs from the recorded source, ref, and- path with `force: true`, and the Agent Server keeps the enabled state.--## 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.--### Optional app backend views--Schema 1 routed pages may embed an app-owned HTTP UI through the optional-`host.appBackendView` helper. The helper is present only when all parts of the-Agent Server bridge contract are available:--- `/server_info.capabilities` contains `canvas_app_backend_bridge_v1`;-- `/server_info.app_backend_ingress_url` is a valid HTTP(S) URL; and-- the installed `@openhands/typescript-client` exports- `CanvasExtensionsClient.createAppBackendSession()` and- `revokeAppBackendSession()`.--Extensions call `host.appBackendView.mount({ container })`; they never receive-an Agent Server session key, inspect local storage, construct an ingress origin,-or derive one from `window.location`. Canvas requests a short-lived session from-the discovered ingress, validates that the returned URL has the same origin,-and renders it in an iframe using only the server-provided allowlisted sandbox-tokens. `allow-same-origin` is required so authenticated fetch, WebSocket, and-Worker APIs retain the app ingress origin and partitioned session cookie; the-separate ingress origin is the authority boundary. Top-navigation, downloads,-and storage-access tokens remain rejected. The host owns loading, safe errors,-retry, a validated new-tab fallback, session revocation, and disposal on page-unmount or backend switch.--This remains additive to schema 1. Self-contained ESM loading, routed page-registration, and the native editor are unchanged. There is no generic runtime,-VS Code app, arbitrary URL proxy, mandatory sidecar, or frontend tarball loader.--The pinned `@openhands/typescript-client` `1.53.0` ships the bridge API-(first defined in draft `OpenHands/software-agent-sdk#5272`), so the client-export requirement above is satisfied by a released client. The helper is-feature-detected at runtime on the live Agent Server: `server_info.capabilities`-must advertise `canvas_app_backend_bridge_v1` and `app_backend_ingress_url`-must be a valid HTTP(S) URL. Canvas requires Agent Server `1.51.0` or newer,-which is above the first release exposing this bridge contract.--## 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}`. The Customize inventory is-`/apps`; there is no bare `/extensions` page. 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 > Apps 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/skills/e2e-testing/references/guide.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 formatdiff --git a/specs/form-feedback.md b/specs/form-feedback.mddeleted file mode 100644index 0627ac6412..0000000000--- a/specs/form-feedback.md+++ /dev/null@@ -1,4 +0,0 @@-# Form feedback theme contract--### FF-001: Theme-aware validation and load errors-- [x] Form validation, profile load failures, missing-model guidance, and inline service errors shall use the host-overridable feedback-error text role. Invalid manifest control borders shall use semantic danger. Preserve messages, ARIA state, validation, retries, save behavior, and transport contracts; small error text must remain readable in all five themes.diff --git a/specs/home-launcher.md b/specs/home-launcher.mddeleted file mode 100644index 0147c7a051..0000000000--- a/specs/home-launcher.md+++ /dev/null@@ -1,11 +0,0 @@-# Home launcher specs--### HL-001: Readable Code/Automate mode toggle--- [x] The selected mode label, and an unselected label while hovered, shall use the `contrast` high-emphasis ink on the `--oh-interactive-hover` pill. The built-in palettes keep that pairing at 4.5:1 or better: white in dark palettes, dark ink in Light+ and Solarized Light. Embedding roots may override `--oh-contrast`, and the toggle follows the nearest `[data-agent-server-ui]` scope. Mode selection, keyboard and radio semantics, and the pill animation are unchanged.--### HL-002: Dismissible Recommended automations rail--- [x] Home's Recommended automations rail shall show an X named "Hide Recommended automations" in its header. On fine-pointer devices the X appears while the rail is hovered or holds keyboard focus; on touch and coarse-pointer devices it is always visible.-- [x] Clicking the X shall remove the whole rail from Home at once (heading, cards and bottom inset) and turn **Show Recommended automations** in Application settings off without a reload. Turning that switch back on shall restore the rail on the next Home render.-- [x] The X and the switch shall share one browser-scoped preference that defaults to shown and survives a reload. The rails in the automations empty state and the onboarding say-hello step shall never show the X and shall ignore the preference.diff --git a/specs/llm-defaults.md b/specs/llm-defaults.mddeleted file mode 100644index ac520d02e6..0000000000--- a/specs/llm-defaults.md+++ /dev/null@@ -1,10 +0,0 @@-# 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 a conversation-start request that carries a raw agent spec (the local planner). Agent Profile launches take the model from the referenced LLM profile.-- [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 planner's encrypted payload path).diff --git a/specs/mcp-secret-selection.md b/specs/mcp-secret-selection.mddeleted file mode 100644index c9b5e29b11..0000000000--- a/specs/mcp-secret-selection.md+++ /dev/null@@ -1,11 +0,0 @@-# MCP credential selection--### MCP-005: Credential selection stays readable in every theme--- [x] The catalog's **Also save as secret** row follows the active palette,- with readable labels and secret names in both checked and unchecked states.-- [x] The selected switch uses Canvas's shared toggle appearance; color alone- does not communicate the checkbox state.-- [x] Long secret names and the help control remain inside the row on phones.-- [x] Label clicks and Space operate the native checkbox. Keyboard focus is- visible, and opening help does not change the selection.diff --git a/specs/mcp-settings.md b/specs/mcp-settings.mddeleted file mode 100644index c199ae9f48..0000000000--- a/specs/mcp-settings.md+++ /dev/null@@ -1,53 +0,0 @@-# 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.- On a cloud backend, an add or update first reads the stored catalog and- writes it back in full, because the cloud replaces the whole catalog for- an `mcp_config` map without `null` entries (OHE-3248).-- [x] An MCP mutation shall never use redacted or encrypted settings snapshots- as its mutation base. On a cloud backend, untouched sibling servers are- resent verbatim from the redacted settings read (the cloud restores their- secrets by key); redacted values are still never used as input for the- mutated server.-- [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.--### MCP-004: Form feedback follows readable theme text roles--- [x] Custom-server validation and connection feedback, and catalog-install- errors, use the selected theme's error/success text roles.-- [x] Both text roles meet 4.5:1 against the modal surface in every built-in- palette, independently of the danger/success control colors.-- [x] Embedded host overrides for those roles survive palette changes.--### MCP-006: Library installs never dead-end--- [x] An entry keeps its preferred installable option, such as an API-key- fallback, when one exists.-- [x] When an entry's only remote option is OAuth, including an option that- names provider OAuth endpoints, Install connects through the MCP server's- own OAuth discovery. The catalog's provider endpoints, scopes and client- authentication are not sent.-- [x] When no option can be installed, the dialog says so and Install is- disabled. Install never does nothing silently.diff --git a/specs/settings-switches.md b/specs/settings-switches.mddeleted file mode 100644index 67965ccf66..0000000000--- a/specs/settings-switches.md+++ /dev/null@@ -1,10 +0,0 @@-# Settings switch contracts--### SSW-001: Settings switches expose native checkbox interaction--- [x] Enabled settings switches participate in Tab order and expose their- label and checked state through the native checkbox accessibility role.-- [x] Space and label clicks toggle the same value. Keyboard focus is visible- on the displayed control and label.-- [x] Disabled switches remain disabled, are skipped by Tab, and preserve their- controlled checked state. Toggle position does not change these behaviors.diff --git a/specs/toast-notifications.md b/specs/toast-notifications.mddeleted file mode 100644index 08da72dff0..0000000000--- a/specs/toast-notifications.md+++ /dev/null@@ -1,5 +0,0 @@-# Toast notification specs--### TN-001: Readable toast text in every theme--- [x] Success, warning, loading and error toasts shall draw their text in the `contrast` high-emphasis ink on the `--oh-color-tertiary` toast surface. The built-in palettes keep that pairing at 4.5:1 or better: white in dark palettes, dark ink in Light+ and Solarized Light. Error toasts keep the status-error icon as their error cue. Embedding roots may override `--oh-contrast`, and toasts follow the nearest `[data-agent-server-ui]` scope. Toast copy, icons, placement, duration and links are unchanged.diff --git a/specs/warning-feedback.md b/specs/warning-feedback.mddeleted file mode 100644index 41d4c3c483..0000000000--- a/specs/warning-feedback.md+++ /dev/null@@ -1,10 +0,0 @@-# WN-001 β Readable warning feedback--**Spec ID:** WN-001-**Status:** Implemented--Small warning text and warning icons use the `feedback-warning` text role, backed by `--oh-feedback-warning`. The built-in role meets 4.5:1 on the theme surfaces used by the Home no-LLM banner, Canvas Apps trust notice, ACP conflict messages, and required-secret onboarding warning. Light+ and Solarized Light use darker text shades while retaining the existing brand warning color for controls and tint.--Embedding roots may override the role. The UI follows the nearest `[data-agent-server-ui]` scope. Changing the role does not change warning copy, validation, routing, credential state, or trust controls.--Real browser coverage verifies the Home icon and Apps trust notice follow the host override. The theme contract checks every built-in palette.diff --git a/specs/workspace-file-discovery.md b/specs/workspace-file-discovery.mddeleted file mode 100644index cc427d8bf9..0000000000--- a/specs/workspace-file-discovery.md+++ /dev/null@@ -1,20 +0,0 @@-# Workspace File Discovery--### WFD-001: Configurable local workspace discovery--- With no saved configuration, list at most 2,000 regular files using the existing directory exclusions.-- Users can replace directory exclusions with name or workspace-relative path patterns. `*/bin` excludes nested `bin` directories while preserving root `bin`.-- Quote every configured pattern as shell data. Patterns cannot execute commands.-- A zero file limit means unlimited. A positive integer bounds the returned paths.-- Optional symlink inclusion lists links to regular files without traversing directory links.-- Read one extra path for a finite limit. Show an incomplete-tree message only when more paths exist than the configured limit.-- Cloud file listing keeps its existing request and behavior.--### WFD-002: Workspace-scoped server persistence--- The local backend owns `misc_settings.app_preferences.workspace_file_discovery`, keyed by working directory.-- Save a sparse map containing only the edited workspace so other workspace preferences survive the server's deep merge.-- Conversations sharing a workspace use its configuration. A different workspace or backend uses its own configuration or defaults.-- Saved preferences survive reload. Missing or invalid values fall back to conservative defaults.-- Reset prepares the defaults for Save; Cancel discards the form draft. Failed saves keep the dialog open with an error.-- Switching workspace or backend discards the open editor. Cloud never displays the editor or saves these settings.diff --git a/specs/workspace-upload-path.md b/specs/workspace-upload-path.mddeleted file mode 100644index ebcf480d09..0000000000--- a/specs/workspace-upload-path.md+++ /dev/null@@ -1,16 +0,0 @@-# 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.