specs/canvas-extensions.md

# 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