Canvas Extensions architecture teardown

Studied from software-agent-sdk through 2002f9804 and the unmerged Agent Canvas vertical slice at a52dc90d, plus the SVG-edit example. Current-state check: 27 August 2026.

A Canvas Extension is a JavaScript bundle installed beside an Agent Server and loaded by Agent Canvas to add UI. In v1, “UI” means a page and a sidebar link. The backend stores, validates, and serves the bundle; the browser imports it and hands it a small host API.

First: do not confuse the four extension nouns

The naming is defensible only if this boundary stays crisp: skills and plugins change what the agent can do; Canvas Extensions change what the human sees and can operate. The distribution plumbing is shared with plugins. The runtime is deliberately not.

The package: tiny on purpose

my-dashboard/
├── canvas-extension.json
└── dist/
    └── extension.js       # self-contained browser ESM; no chunks or bare imports

{
  "schema_version": 1,
  "name": "my-dashboard",
  "display_name": "My dashboard",
  "version": "0.1.0",
  "entrypoint": "dist/extension.js",
  "contributes": {
    "pages": [
      { "id": "home", "title": "Dashboard", "path": "/home" }
    ]
  }
}

The bundle exports one function. It does not receive React. It receives a host object and registers an imperative DOM mount callback:

export function activate(host) {
  return host.registerPage("home", ({ container, path, navigate }) => {
    container.textContent = `Nested path: ${path}`;
    return () => container.replaceChildren();
  });
}

Who owns what

The whole mechanism

sequenceDiagram
  actor U as User
  participant UI as Agent Canvas
  participant AS as Agent Server
  participant IM as InstallationManager
  participant FS as ~/.openhands/canvas-extensions
  participant JS as Browser JS realm

  U->>UI: Install source + optional ref/subpath
  UI->>AS: POST /api/canvas-extensions/install
  AS->>IM: fetch, parse, validate, copy, record
  IM->>FS: package + .installed.json (enabled=false)
  AS-->>UI: installation + parsed manifest
  U->>UI: Enable after trust warning
  UI->>AS: PATCH installed/name { enabled: true }
  UI->>AS: GET installed/name/bundle (authenticated)
  AS->>FS: re-read manifest + re-check containment
  AS-->>UI: JavaScript text
  UI->>JS: Blob URL + dynamic import
  JS-->>UI: activate(host)
  JS->>UI: host.registerPage(declaredId, mount)
  UI->>UI: add route target + sidebar item
  U->>UI: Open /extensions/name/page
  UI->>JS: mount({ container, path, navigate })
    

Why the Blob detour? The bundle endpoint requires the Agent Server session key. A module import() cannot attach that header, so Canvas fetches text with its authenticated client, creates a temporary blob: URL, imports it, then revokes the URL.

The design patterns hiding underneath

What the design gets genuinely right

• Install is not execute. New and manually discovered Canvas Extensions are forced disabled, and the UI asks before first enable.
• Filesystem containment is checked twice. Textual .., absolute entrypoints, missing files, directories, dangling links, symlink cycles, and symlink escapes are rejected. The bundle path is resolved again immediately before serving.
• Backend switching is modeled, not patched. Backend identity is present in query keys, activation identity, and authenticated request clients.
• Contribution namespaces are simple. Routes live under /extensions/{extension-name}/..., so two extensions can both contribute /dashboard without colliding.
• The first contribution type is narrow. Proving pages before themes, conversation panels, slots, and event visualizers is the correct delivery order.
• The spec tells the truth about trust. It explicitly says same-realm code is trusted and cleanup is best-effort. That honesty is rare and valuable.

The hard truth

Architecture scorecard

Should same-realm JavaScript be rejected?

Not automatically. VS Code extensions, browser extensions, and desktop plugins all make different trust trades. A local, self-hosted tool can legitimately say: “this is code you trust as much as the app.” Same-realm execution buys rich integration, low latency, a tiny ABI, and freedom from an RPC serialization layer.

But the product must choose one of two honest identities:

The worst option is the middle: same-realm code with a permissions screen that creates the feeling of containment. The current spec avoids that lie. It should keep avoiding it.

What I would change, in order

The final judgment

The code has good instincts. It separates agent extensions from UI extensions. It uses a generic install adapter rather than copying plugin machinery. It treats backend identity as state, rechecks path containment at the last responsible moment, makes installation non-executing by default, and starts with one narrow contribution type.

Its weakness is not sloppy implementation. Its weakness is an unresolved product identity. The machinery is built like the beginning of an ecosystem, while the runtime trust model is suitable only for code the user would happily paste into Canvas's own source tree. Until that choice is resolved, every new contribution type multiplies authority faster than it multiplies value.

Source trail

• software-agent-sdk #4361 — manifest validation and entrypoint containment
• software-agent-sdk #4364 — persistence and disabled-by-default behavior
• software-agent-sdk #4374 — staged refresh and swap
• software-agent-sdk 2002f9804 — REST router, bundle delivery, parsed manifests
• Agent Canvas a52dc90d — frontend vertical slice
• tracking epic #16289 — current phased plan and completion state
• Agent Canvas #16492 — origin-readable backend API keys
• software-agent-sdk #4354 — generated client and capability discovery gap