kandev/docs/specs/ui/embedded-vscode-executor-availability.md

---
status: shipped
created: 2026-07-30
owner: Kandev
---

# Embedded VS Code Executor Availability

## Why

Kandev starts **VS Code (Embedded)** as a code-server process inside the active task session's
execution environment. The Kandev backend host and that execution environment can use different
operating systems: a Windows desktop can run a Linux Docker task, while a Linux Kandev server can
control another supported remote runtime.

The previous host-wide Windows rule therefore hid a working embedded editor from every task on a
Windows Kandev host, including Linux-backed Docker tasks. Availability must follow the environment
that will actually run code-server.

## What

- The active task session's executor runtime is authoritative for **VS Code (Embedded)**
  availability. The Kandev backend host matters only when that executor runs directly on the host.
- The backend reports an explicit `embedded_vscode` capability for each task-session status
  response. The frontend does not reconstruct support from executor names or browser platform
  data.
- Kandev computes support as follows:

  | Executor type | Execution platform used for the decision | Embedded VS Code |
  | --- | --- | --- |
  | Local / Local PC (`local`) | Kandev backend host | Available on Linux and macOS; unavailable on Windows |
  | Worktree (`worktree`) | Kandev backend host | Available on Linux and macOS; unavailable on Windows |
  | Local Docker (`local_docker`) | Linux container | Available, including when Kandev runs on Windows |
  | Remote Docker (`remote_docker`) | Linux container | Available |
  | Sprites (`sprites`) | Linux sandbox | Available |
  | SSH (`ssh`) | Supported remote platform | Available while SSH execution remains limited to Linux and macOS |
  | Unknown or unresolved executor | Unknown | Unavailable |

- When Kandev later supports an SSH or other executor on additional operating systems, the backend
  capability resolver must be updated before advertising embedded-editor support there.
- The task-detail topbar's primary editor action and adjacent menu use the active session's
  capability. Switching sessions updates the compatible editor set.
- The existing enabled and installed checks still apply to every editor. Only
  `internal_vscode` is affected by the new capability.
- If a saved default is unavailable for the active session, the primary action uses the first
  remaining compatible editor without changing the saved preference.
- If no compatible editor remains, both topbar editor controls are disabled and no editor is
  launched.
- A direct request to open `internal_vscode` for an unsupported or unresolved session is rejected
  as an unavailable editor. UI filtering is not the enforcement boundary.
- The visitor's browser or WebView operating system never controls this capability.
- The phone task-detail layout remains unchanged. It continues to use its compact mobile topbar
  without the desktop editor action.

## API surface

The `task.session.status` WebSocket response includes:

```json
{
  "capabilities": {
    "embedded_vscode": true
  }
}
```

`capabilities` is backend-owned session execution metadata. `embedded_vscode` is always a boolean
for an authorized, existing session. Missing capability data from an older backend, a missing
executor, or an unrecognized runtime is treated as `false` by the frontend.

`POST /api/v1/task-sessions/:id/open-editor` returns the existing editor-unavailable conflict
response when `internal_vscode` is selected for a session whose capability is false.

The boot runtime's `hostOS` field is removed because it is no longer an editor-availability
contract and has no other consumer.

## Failure modes

- If task-session status has not loaded yet, the embedded editor is withheld while other enabled
  editors remain usable.
- If the executor lookup or runtime mapping fails, the backend reports
  `embedded_vscode: false`.
- A stale or handcrafted client cannot bypass the rule: the open-editor service resolves the
  session executor and rejects unsupported embedded-editor requests.
- A supported runtime can still fail during code-server download or startup. Existing panel errors
  and task-environment logs remain the diagnostic surface for network, archive, process, and proxy
  failures.
- Changing active sessions cannot reuse the previous session's capability.

## Scenarios

- **GIVEN** Kandev runs on Windows and the active session uses Local or Worktree, **WHEN** a user
  opens the task-detail editor menu, **THEN** **VS Code (Embedded)** is absent and other compatible
  editors remain available.
- **GIVEN** Kandev runs on Windows and the active session uses Local Docker, **WHEN** a user opens
  the task-detail editor menu, **THEN** **VS Code (Embedded)** is available.
- **GIVEN** a task has one unsupported local session and one supported Docker session, **WHEN** the
  user switches between them, **THEN** the editor menu follows the newly active session.
- **GIVEN** Kandev runs on Linux or macOS and the active session uses Local or Worktree, **WHEN** a
  user opens the editor menu, **THEN** **VS Code (Embedded)** is available.
- **GIVEN** the saved default is **VS Code (Embedded)** but the active session does not support it,
  **WHEN** the primary editor action is activated, **THEN** Kandev opens the first compatible
  fallback without changing the saved default.
- **GIVEN** the active session executor is missing or unrecognized, **WHEN** task details render,
  **THEN** the embedded editor is absent and cannot be opened through the API.
- **GIVEN** an unsupported session, **WHEN** a client directly requests `internal_vscode`,
  **THEN** the backend returns the editor-unavailable conflict response.
- **GIVEN** a visitor's browser reports Windows but the active task runtime is supported, **WHEN**
  the editor menu opens, **THEN** **VS Code (Embedded)** remains available.
- **GIVEN** a phone user opens task details for any executor, **WHEN** the mobile topbar renders,
  **THEN** no desktop editor action is exposed and the header does not overflow horizontally.

## Out of scope

- Replacing code-server with Microsoft VS Code Server.
- Adding or packaging a native Windows code-server runtime.
- Changing Kandev's pinned code-server version or installation source.
- Adding Windows as a supported SSH execution platform.
- Proactively hiding the embedded editor from editor settings, file-level **Open with** menus,
  layout presets, or the Dockview add-panel menu. The backend availability guard still applies to
  open-editor API requests.
- Changing external editor discovery, custom editor commands, or hosted-editor behavior.
- Adding an editor action to the phone task topbar.

## Implementation plan

- [Embedded VS Code executor availability plan](../../plans/embedded-vscode-executor-availability/plan.md)