openhands-extensions 0.28.0__tar.gz → 0.29.0__tar.gz

openhands_extensions-0.29.0/.release-please-manifest.json

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

{openhands_extensions-0.28.0 → openhands_extensions-0.29.0}/AGENTS.md

@@ -6,7 +6,7 @@ It contains **shareable skills and plugins** that can be loaded by OpenHands (CL
 
 ## Cross-Repository Boundaries
 
-This repository owns the public registry of reusable OpenHands skills, plugins, automations, and integrations. These extensions are consumed by OpenHands applications and SDK-based clients.
+This repository owns the public registry of reusable OpenHands skills, plugins, Agent Canvas Apps, automations, and integrations. These extensions are consumed by OpenHands applications and SDK-based clients.
 
 Related repositories have distinct responsibilities:
 
@@ -49,7 +49,12 @@ Before opening a PR:
   - `plugins/<plugin-name>/hooks/` — lifecycle hooks (optional)
   - `plugins/<plugin-name>/scripts/` — utility scripts (optional)
 
-There is no application code here; the primary artifacts are Markdown skill definitions and plugin configurations, which can contain `scripts/`, `hooks/` sub-directories.
+- `apps/` — a catalog of Agent Canvas Apps (beta), **one directory per app**.
+  - `apps/<app-name>/canvas-extension.json` — the App manifest (Canvas Extensions API v1)
+  - `apps/<app-name>/extension.js` — the browser ESM entrypoint exporting `activate(host)`
+  - `apps/catalog.json` — the registry catalog, exposed as `APPS_CATALOG` from `@openhands/extensions/apps`
+
+Most content is Markdown skill definitions and plugin configurations; the executable parts are plugin `scripts/` and `hooks/` plus the browser ESM App packages under `apps/`, each of which may ship its own `scripts/` and build sub-directories.
 
 ## How client code uses this repo
 

{openhands_extensions-0.28.0 → openhands_extensions-0.29.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: openhands-extensions
-Version: 0.28.0
+Version: 0.29.0
 Summary: OpenHands extensions, plugins, and skills (Python bindings for the integration catalog)
 License-File: LICENSE
 Requires-Python: >=3.12

{openhands_extensions-0.28.0 → openhands_extensions-0.29.0}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openhands/extensions",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "Public OpenHands extension catalogs for skills, plugins, integrations, and automation templates.",
   "license": "MIT",
   "type": "module",

{openhands_extensions-0.28.0 → openhands_extensions-0.29.0}/plugins/openhands/skills/openhands-automation/references/custom-automation.md

@@ -249,6 +249,7 @@ uv pip install -q openhands-sdk openhands-workspace openhands-tools
 import os
 
 from openhands.sdk import Conversation
+from openhands.sdk.automation import automation_conversation_kwargs
 from openhands.tools.preset.default import get_default_agent
 from openhands.workspace import OpenHandsCloudWorkspace
 
@@ -266,13 +267,48 @@ with OpenHandsCloudWorkspace(
 ) as workspace:
     llm = workspace.get_llm()
     agent = get_default_agent(llm=llm, cli_mode=True)
-    conversation = Conversation(agent=agent, workspace=workspace)
+    conversation = Conversation(
+        agent=agent,
+        workspace=workspace,
+        **automation_conversation_kwargs(),
+    )
     conversation.send_message("Your automation prompt here")
     conversation.run()
     conversation.close()
 # OpenHandsCloudWorkspace.__exit__ fires the completion callback here.
 ```
 
+### Link automation conversations to run telemetry
+
+When an automation script starts a conversation, preserve the trace context that the automation service injected into the run. This links the conversation span to the triggering webhook, scheduler dispatch, and run record.
+
+- SDK conversations: pass `**automation_conversation_kwargs()` into every `Conversation(...)` call.
+- Direct agent-server API calls: merge `automation_observability_headers()` into the headers for each `POST /api/conversations` request.
+- If you add your own conversation tags, pass them through `conversation_tags={...}` instead of replacing the helper output.
+
+```python
+from openhands.sdk import Conversation
+from openhands.sdk.automation import (
+    automation_conversation_kwargs,
+    automation_observability_headers,
+)
+
+conversation = Conversation(
+    agent=agent,
+    workspace=workspace,
+    **automation_conversation_kwargs(),
+)
+
+headers = {
+    "X-Session-API-Key": api_key,
+    **automation_observability_headers(span_name="automation.conversation"),
+}
+# Use these headers when creating a backend conversation directly.
+# httpx.post(f"{agent_url}/api/conversations", headers=headers, json=payload)
+```
+
+The built-in prompt and plugin presets use this helper. Custom scripts should do the same for every new conversation so traces, observability metadata, and automation conversation tags stay attached.
+
 ### Selecting an LLM profile
 
 The automation service injects an `AUTOMATION_MODEL` environment variable holding the **LLM profile name** the automation should run with. This is the profile a user selects when editing the automation, or — when none is selected — a snapshot of the user's active profile taken when the automation was created. To honor it on every run, read `AUTOMATION_MODEL` and pass it to `workspace.get_llm(profile_name=...)`:
@@ -299,13 +335,27 @@ Conversations started during a run remain accessible in the OpenHands UI after t
 
 ```python
 # Default: conversation persists after close (users can view/continue it)
-conversation = Conversation(agent=agent, workspace=workspace)
+conversation = Conversation(
+    agent=agent,
+    workspace=workspace,
+    **automation_conversation_kwargs(),
+)
 
 # Explicitly persist (same as default)
-conversation = Conversation(agent=agent, workspace=workspace, delete_on_close=False)
+conversation = Conversation(
+    agent=agent,
+    workspace=workspace,
+    delete_on_close=False,
+    **automation_conversation_kwargs(),
+)
 
 # Delete conversation resources on close
-conversation = Conversation(agent=agent, workspace=workspace, delete_on_close=True)
+conversation = Conversation(
+    agent=agent,
+    workspace=workspace,
+    delete_on_close=True,
+    **automation_conversation_kwargs(),
+)
 ```
 
 The agent server itself persists until it times out or is manually deleted; this is managed by the automation service, not by the workspace.
@@ -339,7 +389,11 @@ else:
     with OpenHandsCloudWorkspace(local_agent_server_mode=True, cloud_api_url=api_url, cloud_api_key=api_key) as workspace:
         llm = workspace.get_llm()
         agent = get_default_agent(llm=llm, cli_mode=True)
-        conversation = Conversation(agent=agent, workspace=workspace)
+        conversation = Conversation(
+            agent=agent,
+            workspace=workspace,
+            **automation_conversation_kwargs(),
+        )
         conversation.send_message(f"Investigate these alerts and open GitHub issues: {alerts}")
         conversation.run()
         conversation.close()
@@ -358,7 +412,11 @@ from openhands.sdk.conversation.state import ConversationExecutionStatus
 with OpenHandsCloudWorkspace(local_agent_server_mode=True, cloud_api_url=api_url, cloud_api_key=api_key) as workspace:
     llm = workspace.get_llm()
     agent = get_default_agent(llm=llm, cli_mode=True)
-    conversation = Conversation(agent=agent, workspace=workspace)
+    conversation = Conversation(
+        agent=agent,
+        workspace=workspace,
+        **automation_conversation_kwargs(),
+    )
     conversation.send_message("Run a long analysis task")
     # Conversation is now running asynchronously in the agent server.
 
@@ -404,7 +462,12 @@ stop_hook = HookConfig(
 with OpenHandsCloudWorkspace(local_agent_server_mode=True, cloud_api_url=api_url, cloud_api_key=api_key) as workspace:
     llm = workspace.get_llm()
     agent = get_default_agent(llm=llm, cli_mode=True)
-    conversation = Conversation(agent=agent, workspace=workspace, hook_config=stop_hook)
+    conversation = Conversation(
+        agent=agent,
+        workspace=workspace,
+        hook_config=stop_hook,
+        **automation_conversation_kwargs(),
+    )
     conversation.send_message("Do some long-running work")
     # Don't call run() — the conversation runs asynchronously.
     # When the agent stops, the stop hook will fire the callback.
@@ -765,6 +828,7 @@ import os
 import json
 
 from openhands.sdk import Conversation
+from openhands.sdk.automation import automation_conversation_kwargs
 from openhands.tools.preset.default import get_default_agent
 from openhands.workspace import OpenHandsCloudWorkspace
 
@@ -781,7 +845,11 @@ with OpenHandsCloudWorkspace(
 ) as workspace:
     llm = workspace.get_llm()
     agent = get_default_agent(llm=llm, cli_mode=True)
-    conversation = Conversation(agent=agent, workspace=workspace)
+    conversation = Conversation(
+        agent=agent,
+        workspace=workspace,
+        **automation_conversation_kwargs(),
+    )
     conversation.send_message("Generate a weekly status report")
     conversation.run()
     conversation.close()

{openhands_extensions-0.28.0 → openhands_extensions-0.29.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openhands-extensions"
-version = "0.28.0"
+version = "0.29.0"
 description = "OpenHands extensions, plugins, and skills (Python bindings for the integration catalog)"
 requires-python = ">=3.12"
 dependencies = [

{openhands_extensions-0.28.0 → openhands_extensions-0.29.0}/python/openhands_extensions/_version.py

@@ -18,7 +18,7 @@ from importlib.metadata import PackageNotFoundError, version
 #: Kept in lock-step with pyproject.toml/package.json by the version test.
 #: release-please only rewrites a semver found on the annotated line itself, so
 #: the annotation must stay on the assignment; on its own line it is a no-op.
-_FALLBACK_VERSION = "0.28.0"  # x-release-please-version
+_FALLBACK_VERSION = "0.29.0"  # x-release-please-version
 
 try:
     __version__: str = version("openhands-extensions")

{openhands_extensions-0.28.0 → openhands_extensions-0.29.0}/skills/canvas-extension-api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: canvas-extension-api
-description: This skill should be used when the user asks to "create an OpenHands App", "scaffold a Canvas App", "build an app with the Canvas Extensions API", "build an Agent Canvas App", "bundle a single-file Canvas App", "build a Sidecar-backed Canvas App", "add onboarding for an App service", "add a custom interface to Agent Canvas", "validate an OpenHands App", or mentions Canvas Apps, Agent Canvas extensions, Blob-importable app bundles, registerPage, app pages, Sidecars, or canvas extension packages.
+description: This skill should be used when the user asks to "create an OpenHands App", "scaffold a Canvas App", "build an app with the Canvas Extensions API", "build an Agent Canvas App", "bundle a single-file Canvas App", "build a Sidecar-backed Canvas App", "add onboarding for an App service", "add a custom interface to Agent Canvas", "validate an OpenHands App", "make a Canvas App look native", "match Agent Canvas styles", "style a canvas extension", "reuse OpenHands design tokens", "add native Tailwind classes to an app", or mentions Canvas Apps, Agent Canvas extensions, Blob-importable app bundles, registerPage, app pages, Sidecars, or canvas extension packages.
 ---
 
 # Canvas Extensions API
@@ -195,6 +195,8 @@ Assume activation, mounting, and disposal may happen repeatedly during hot enabl
 
 Render within the supplied `container`; do not replace unrelated Canvas DOM. Scope CSS under an app-specific root class. Prefer Canvas CSS variables with sensible fallbacks rather than copying host implementation classes.
 
+Read `references/native-design.md` before styling an App page. It covers the core rule (reuse tokens, not host internals), the three implementation paths (dependency-free, Tailwind-bundled, existing CSS), the Tailwind v4 theme mapping to host variables, layout and density conventions, copy-ready component recipes, the raw scoped CSS alternative, and a mount-safe style helper. Treat it as the authoritative design reference for Apps.
+
 Provide:
 
 - semantic structure and headings inside the supplied container. Canvas already owns the outer `<main aria-label={page title}>`, so do not add a nested `main` or duplicate page landmark label;
@@ -281,5 +283,6 @@ Summarize:
 - `references/testing-and-installation.md` - test strategy, manual Canvas workflow, and installation coordinates.
 - `references/packaging-recipes.md` - one-file Vite, CSS, assets, Workers, and WASM rules.
 - `references/backend-safety.md` - authenticated requests, command safety, persistence, and prerequisite onboarding.
+- `references/native-design.md` - native Agent Canvas styling: token reuse, Tailwind mapping, layout, component recipes, scoped CSS, and style injection.
 - `references/acceptance-checklist.md` - automated checks and the local install/enable/reload lifecycle.
 - `scripts/validate-extension.mjs` - dependency-free static artifact validator for an App package directory.

openhands_extensions-0.29.0/skills/canvas-extension-api/references/native-design.md

@@ -0,0 +1,250 @@
+# Native OpenHands App design
+
+Build Apps for Agent Canvas that visually belong in the host while remaining a self-contained, safe extension package. Use this reference together with the main `SKILL.md` workflow before changing an App's UI.
+
+## Core rule: reuse tokens, not host internals
+
+Treat an App bundle as an independent frontend. Do not import Agent Canvas React components, utility modules, CSS files, font files, Tailwind configuration, aliases, or private DOM classes. The host imports the App as a self-contained Blob ESM module, so those imports will fail or create fragile coupling.
+
+Reuse the host's stable CSS custom properties instead. Scope every selector under a unique App root class and provide literal fallbacks so the page stays legible outside a current Canvas build. Tailwind utility names such as `bg-base` or `text-contrast` are **not globally available** to an App: they work only after the App's own Tailwind build maps them to the host variables.
+
+Use semantic names (`surface`, `foreground`, `border`, `primary`) rather than copying cool-grey hex values.
+
+## Choose the implementation path
+
+Choose the smallest path that matches the App package:
+
+| App implementation | Recommended styling approach |
+| --- | --- |
+| Dependency-free JavaScript | Inject one scoped CSS string from the entrypoint. Use host custom properties directly. |
+| React/TypeScript with Tailwind | Add an App-local Tailwind theme mapping to the host variables, then compile every class into the single `extension.js` artifact. |
+| Existing CSS module or CSS-in-JS setup | Define the semantic colors and component recipes in the App's own scoped stylesheet. |
+
+Never expect the host Tailwind compiler to scan or compile App source. Never use a CDN Tailwind runtime. Never attach App styles to `:root`, `html`, `body`, or global element selectors.
+
+## Tailwind setup for a bundled App
+
+For Tailwind v4, place an App-local mapping in the App stylesheet. This lets the App use Canvas-like classes while preserving portability:
+
+```css
+@import "tailwindcss";
+
+@theme inline {
+  --color-base: var(--oh-color-base);
+  --color-base-secondary: var(--oh-color-base-secondary);
+  --color-surface: var(--oh-surface);
+  --color-surface-raised: var(--oh-surface-raised);
+  --color-foreground: var(--oh-foreground);
+  --color-contrast: var(--oh-contrast);
+  --color-muted: var(--oh-muted);
+  --color-tertiary-alt: var(--oh-text-dim);
+  --color-border: var(--oh-border);
+  --color-border-subtle: var(--oh-border-subtle);
+  --color-focus: var(--oh-focus);
+  --color-interactive-hover: var(--oh-interactive-hover);
+  --color-primary: var(--oh-color-primary);
+  --color-on-primary: var(--oh-accent-foreground);
+  --color-danger: var(--oh-danger);
+}
+```
+
+Compile this stylesheet into `extension.js`; do not leave a linked CSS asset. For an App without Tailwind, use the matching raw CSS below instead. Use utility recipes only after adding this mapping.
+
+## Layout and density
+
+Let Canvas own the outer page and scrolling region. Do not add a second page shell, `h-screen`, global background, sidebar, or top navigation. Start with `min-h-full`, use `p-4 sm:p-6 lg:p-8`, and constrain dense content with `mx-auto w-full max-w-5xl`. Use `gap-4` for related controls, `gap-6` within sections, and `gap-8` between major sections. Use `rounded-lg` for controls and `rounded-xl` for cards and messages.
+
+Avoid gradients, glass effects, oversize headings, floating shadows, dense borders, and hard-coded dark greys. The native visual language is restrained: dark layered surfaces, cool-grey borders, warm primary actions, direct typography, and short transitions.
+
+## Interaction and state checklist
+
+- Apply `text-contrast` to headings and key labels; use `text-muted` or `text-tertiary-alt` for supporting copy.
+- Use the primary recipe for one dominant action. Use a bordered secondary action for alternatives. Do not make every button primary.
+- Use a 36px (`h-9`) control height and `rounded-lg` for input, select, and standard button controls.
+- Use `focus-visible` rather than removing outlines. Preserve disabled affordance with `disabled:cursor-not-allowed disabled:opacity-60`.
+- Animate only background, border, box-shadow, opacity, or transforms and include `motion-reduce:transition-none`.
+- Scope icon sizing and color within the App. Do not assume HeroUI, Lucide, or host icon packages exist.
+- Use `textContent`, framework escaping, or safe DOM creation for data from requests. Never inject response text with `innerHTML`.
+
+## Semantic token map
+
+| Intent | Host variable | Fallback |
+| --- | --- | --- |
+| Deep page base | `--oh-color-base` | `#0B0E14` |
+| Standard panel | `--oh-color-base-secondary` | `#21252F` |
+| Raised surface | `--oh-surface-raised` | `#2C313F` |
+| Main text | `--oh-contrast` | `#FFFFFF` |
+| Standard text | `--oh-foreground` | `#EEF2F7` |
+| Secondary text | `--oh-muted` | `#A3B0C4` |
+| Muted placeholder text | `--oh-text-dim` | `#7E8A9E` |
+| Standard border | `--oh-border` | `#4B5468` |
+| Subtle divider | `--oh-border-subtle` | `#383F50` |
+| Focus ring | `--oh-focus` | `#FFFFFF` |
+| Primary surface | `--oh-color-primary` | `#C9B974` |
+| Primary text | `--oh-accent-foreground` | `#0B0E14` |
+| Danger | `--oh-danger` | `#E76A5E` |
+| Success | `--oh-success` | `#A5E75E` |
+
+## Copy-ready Tailwind recipes
+
+Use these recipes only after mapping the semantic colors in the App-local Tailwind configuration above.
+
+### Content shell
+
+```tsx
+<div className="min-h-full p-4 sm:p-6 lg:p-8 text-foreground">
+  <div className="mx-auto flex w-full max-w-5xl flex-col gap-8">...</div>
+</div>
+```
+
+Do not use `h-screen`, `min-h-screen`, a host-like global background, or a nested `<main>`; Canvas supplies the page landmark and scroll context.
+
+### Page heading
+
+```tsx
+<header className="flex flex-col gap-2 sm:flex-row sm:items-start sm:justify-between">
+  <div className="min-w-0">
+    <h1 className="text-xl font-semibold tracking-tight text-contrast">Page title</h1>
+    <p className="mt-1 text-sm text-muted">Short supporting description.</p>
+  </div>
+</header>
+```
+
+### Card or section
+
+```tsx
+<section className="rounded-xl border border-border bg-base-secondary p-4 sm:p-6">
+  <h2 className="text-base font-medium text-contrast">Section title</h2>
+  <p className="mt-1 text-sm text-muted">Explain the section briefly.</p>
+  <div className="mt-5 flex flex-col gap-4">...</div>
+</section>
+```
+
+Use `border-border-subtle` for dividers inside an existing card. Avoid default card shadows.
+
+### Controls and buttons
+
+```tsx
+const control =
+  "h-9 min-h-9 rounded-lg transition-[background-color,border-color,box-shadow,opacity] duration-75 motion-reduce:transition-none";
+
+const field = `${control} w-full min-w-0 border border-border bg-base-secondary px-3 text-sm text-contrast placeholder:text-tertiary-alt focus:border-contrast/40 focus:ring-1 focus:ring-contrast/20 focus:outline-none disabled:cursor-not-allowed disabled:opacity-60`;
+
+const primaryButton = `${control} inline-flex w-fit items-center justify-center gap-2 bg-primary px-3 text-sm font-normal text-on-primary hover:opacity-80 disabled:cursor-not-allowed disabled:opacity-30`;
+
+const secondaryButton = `${control} inline-flex w-fit items-center justify-center gap-2 border border-border bg-base-secondary px-3 text-sm font-normal text-contrast hover:bg-surface-raised disabled:cursor-not-allowed disabled:opacity-30`;
+```
+
+Use `label` plus `htmlFor`, keep field hints in `text-xs text-muted`, and express validation with `aria-invalid`, a `border-red-500`, and a linked `role="alert"` message using `text-xs text-red-400`.
+
+### Toolbar and responsive grid
+
+```tsx
+<div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+  <div className="min-w-0">...</div>
+  <div className="flex flex-wrap items-center gap-2">...</div>
+</div>
+
+<div className="grid gap-4 md:grid-cols-2 xl:grid-cols-3">...</div>
+```
+
+### Informational, error, and empty state
+
+```tsx
+<div className="rounded-xl border border-border bg-base-secondary p-6 text-center">
+  <h2 className="text-base font-medium text-contrast">Nothing here yet</h2>
+  <p className="mt-2 text-sm text-muted">Describe the next useful action.</p>
+  <button className={`${primaryButton} mt-4`}>Create item</button>
+</div>
+
+<div role="alert" className="rounded-xl border border-red-500/40 bg-red-500/10 px-4 py-3 text-sm text-red-200">
+  The request could not be completed.
+</div>
+```
+
+Use `animate-pulse` with `motion-reduce:animate-none` only for short loading placeholders; reserve space with shapes matching loaded cards or rows.
+
+### Compact tabs
+
+```tsx
+<div role="tablist" aria-label="View options" className="flex w-fit gap-1 rounded-lg border border-border bg-base-secondary p-1">
+  <button role="tab" aria-selected="true" className="rounded-md bg-interactive-hover px-3 py-1.5 text-sm text-contrast">Overview</button>
+  <button role="tab" aria-selected="false" className="rounded-md px-3 py-1.5 text-sm text-muted hover:bg-surface-raised hover:text-contrast">Activity</button>
+</div>
+```
+
+Implement keyboard tab behavior when tabs change content; use regular buttons for simple filters.
+
+## Raw scoped CSS alternative
+
+Use this approach for dependency-free Apps. Apply it only after inserting an App root such as `.acme-dashboard`.
+
+```css
+.acme-dashboard {
+  color: var(--oh-foreground, #EEF2F7);
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+.acme-dashboard .card {
+  border: 1px solid var(--oh-border, #4B5468);
+  border-radius: 12px;
+  background: var(--oh-color-base-secondary, #21252F);
+  padding: 1.5rem;
+}
+.acme-dashboard .field,
+.acme-dashboard .button {
+  min-height: 2.25rem;
+  border-radius: 8px;
+  transition: background-color 75ms, border-color 75ms, box-shadow 75ms, opacity 75ms;
+}
+.acme-dashboard .field {
+  width: 100%; border: 1px solid var(--oh-border, #4B5468);
+  background: var(--oh-color-base-secondary, #21252F);
+  color: var(--oh-contrast, #FFF); padding: 0 0.75rem;
+}
+.acme-dashboard .field:focus-visible,
+.acme-dashboard .button:focus-visible {
+  outline: none; border-color: color-mix(in srgb, var(--oh-contrast, #FFF) 40%, transparent);
+  box-shadow: 0 0 0 1px color-mix(in srgb, var(--oh-contrast, #FFF) 20%, transparent);
+}
+.acme-dashboard .button--primary {
+  border: 0; background: var(--oh-color-primary, #C9B974);
+  color: var(--oh-accent-foreground, #0B0E14); padding: 0 0.75rem;
+}
+@media (prefers-reduced-motion: reduce) {
+  .acme-dashboard .field, .acme-dashboard .button { transition: none; }
+}
+```
+
+## Mount-safe injected style helper
+
+Use one marker per mounted App root and remove the node during cleanup.
+
+```js
+function installStyles(css, marker) {
+  const style = document.createElement("style");
+  style.dataset.canvasAppStyle = marker;
+  style.textContent = css;
+  document.head.append(style);
+  return () => style.remove();
+}
+
+// During mount:
+const disposeStyles = installStyles(STYLES, "acme-dashboard");
+const root = document.createElement("div");
+root.className = "acme-dashboard";
+container.append(root);
+return () => {
+  disposeStyles();
+  root.remove();
+};
+```
+
+If more than one page can mount concurrently, ref-count the marker or inject its stylesheet once in `activate` and remove it in the activation disposer.
+
+## Verify before delivery
+
+- Confirm extension markup uses a unique root class and no App CSS leaks outside it.
+- Confirm styles survive a real Canvas mount, route remount, disable/re-enable cycle, and host dark surface backgrounds.
+- Confirm `extension.js` has no unresolved CSS import, bare package import, extra CSS chunk, or Node global.
+- Run the Canvas extension static validator plus the App's lint, tests, and build.
+- Report whether the App uses direct host variables or an App-local Tailwind mapping, and list the tested states.

{openhands_extensions-0.28.0 → openhands_extensions-0.29.0}/skills/index.js

@@ -103,9 +103,9 @@ export const SKILLS_CATALOG = [
   },
   {
     "name": "canvas-extension-api",
-    "description": "This skill should be used when the user asks to \"create an OpenHands App\", \"scaffold a Canvas App\", \"build an app with the Canvas Extensions API\", \"build an Agent Canvas App\", \"bundle a single-file Canvas App\", \"build a Sidecar-backed Canvas App\", \"add onboarding for an App service\", \"add a custom interface to Agent Canvas\", \"validate an OpenHands App\", or mentions Canvas Apps, Agent Canvas extensions, Blob-importable app bundles, registerPage, app pages, Sidecars, or canvas extension packages.",
+    "description": "This skill should be used when the user asks to \"create an OpenHands App\", \"scaffold a Canvas App\", \"build an app with the Canvas Extensions API\", \"build an Agent Canvas App\", \"bundle a single-file Canvas App\", \"build a Sidecar-backed Canvas App\", \"add onboarding for an App service\", \"add a custom interface to Agent Canvas\", \"validate an OpenHands App\", \"make a Canvas App look native\", \"match Agent Canvas styles\", \"style a canvas extension\", \"reuse OpenHands design tokens\", \"add native Tailwind classes to an app\", or mentions Canvas Apps, Agent Canvas extensions, Blob-importable app bundles, registerPage, app pages, Sidecars, or canvas extension packages.",
     "triggers": [],
-    "content": "# Canvas Extensions API\n\nBuild and validate OpenHands Apps with the Canvas Extensions API, targeting the currently implemented manifest schema 1 and host API 1 routed-page ABI.\n\nUse the naming layers consistently:\n\n- **OpenHands Apps** - customer-facing category for interfaces people discover, install, enable, and open.\n- **Apps for Agent Canvas** - product phrasing that clarifies where apps run.\n- **Canvas Extensions API** - developer platform used to build apps.\n- **Canvas extension package** - technical artifact containing `canvas-extension.json` and its entrypoint.\n- **OpenHands Extensions** - ecosystem and repository umbrella for apps, skills, plugins, automations, and integrations.\n\nUse current product labels in user-facing instructions: **Apps for Agent Canvas**, **Add app**, **Installed apps**, **App source**, **Enable trusted app**, and **Build an app**. Keep technical identifiers such as `canvas-extension.json`, `/api/canvas-extensions/*`, `host.extension`, and `/extensions/*` unchanged unless the target implementation changes them.\n\nTreat apps as trusted, same-realm browser code owned by the active Agent Server. Keep the categories distinct: apps extend what people can do in Agent Canvas, plugins extend agent runtime capabilities, and skills provide agent instructions and knowledge.\n\n\n## Prefer the proven App authoring loop\n\nTreat an App as one authenticated browser dependency graph that Canvas imports from a Blob URL. Do not build a hosted SPA: the production result must be exactly one self-contained browser ESM entrypoint that exports `activate(host)`. Always ship this UI package even when it uses an optional package-owned managed backend or a manual/deployment-owned Sidecar. Make the App page the guided UI for service setup after the App is opened. Never treat a service as another browser chunk or an automatic extension install hook.\n\nFor a new App, create an independent package in the target repository and implement its own UI, tests, and build tooling. Follow the Vite library-build reference in `references/packaging-recipes.md`; do not copy a shared starter or introduce a repository-wide runtime/workspace unless the target repository explicitly requires it.\n\nKeep all source, scripts, dependencies, tests, and checked-in `extension.js` inside the App package. Implement one declared page with explicit root, nested, and unknown-route behavior. Inject scoped CSS per mount and clean it up with framework roots, requests, listeners, timers, Workers, and object URLs. Build validation must verify `dist/extension.js` before synchronizing it to the App root. Do not synchronize an unverified artifact. Use `CHROME_PATH` when the Chrome executable is elsewhere.\n\nFor an existing App, run the reusable static gate before and after its own checks:\n\n```sh\nnode /path/to/canvas-extension-api/scripts/validate-extension.mjs /path/to/app\nnode /path/to/canvas-extension-api/scripts/validate-extension.mjs /path/to/app --dist --marker <required-feature-marker>\n```\n\nTreat the static validator as a gate, not a replacement for the browser Blob smoke test. Read `references/packaging-recipes.md` before adding CSS, raw assets, dynamic modules, Workers, or WASM. Read `references/backend-safety.md` before any Agent Server integration or persistence. Read `references/sidecar-pattern.md` before designing a separately installed service or its onboarding. Read `references/acceptance-checklist.md` before reporting local Canvas compatibility.\n\n## Establish the target\n\nStart by locating the target directory instead of assuming the current workspace. Inspect repository instructions, existing package management, build tooling, tests, and git status before editing.\n\nMake an early architecture decision: browser-only App, Agent Server-integrated App, package-owned managed-backend App, manual/deployment-owned Sidecar App, or explicitly deployment-specific App. Keep the portable host API 1 surface separate from optional Agent Server/host capabilities and deployment-owned behavior.\n\nUse the package-owned managed-backend path only when the target stack includes the lifecycle contract from [software-agent-sdk PR #5270](https://github.com/OpenHands/software-agent-sdk/pull/5270) at `ac7b322ddf7d2e0e90a3643c5e26d848236af9a3`, the bridge contract from [PR #5272](https://github.com/OpenHands/software-agent-sdk/pull/5272) at `6d9c82973e765cce4843d6a2fb52f634efa64293`, and the host version named in `references/v1-contract.md`. Until a release containing both SDK PRs lands, those exact revisions are the minimum Agent Server implementation. Feature-detect `canvas_app_backend_bridge_v1` and `app_backend_ingress_url` through `GET /server_info`; absence is an actionable unsupported state. Do not convert manual Sidecars into managed backends unless the App owns checksum-pinned artifacts for every supported platform.\n\nClarify only choices that materially affect implementation:\n\n- app purpose and page behavior;\n- target repository and subdirectory;\n- dependency-free JavaScript versus a bundled TypeScript/framework project;\n- Agent Server endpoints or host metadata required;\n- whether to build only, install locally, or prepare publication instructions;\n- for a Sidecar: execution location, owner, connection route, secrets and data, lifecycle actions, and portability across Agent Canvas deployments.\n\nDefault to one app with one routed page when requirements are otherwise clear. Keep the first implementation small and dependency-free unless the requested UI clearly benefits from a framework or the repository already has a bundler.\n\nWhen creating multiple Apps in one repository, give every App an independent package root containing its own `canvas-extension.json`, entrypoint, version, tests, README, and build tooling. Do not introduce a monorepo, shared runtime, or common build foundation unless the target repository explicitly requires one. Keep app manifest names globally distinct within the Agent Server installation.\n\nTreat installation as one app per request. The current Customize -> Apps flow accepts one `source`, optional `ref`, and optional `repo_path`; it does not recursively discover or bulk-install every manifest in a repository. For a remote repository, add each app separately using the same source/ref and its own `repo_path`. For a backend-local source, select each app package directory as the source path.\n\nRead `references/v1-contract.md` before implementing unfamiliar Canvas Extensions API behavior. Read `references/connections.md` before connecting to Agent Server, the Automation service, or WebSocket endpoints. Read `references/sidecar-pattern.md` before proposing a Sidecar bridge, onboarding, or operator action. Read `references/testing-and-installation.md` before installing or testing inside Agent Canvas, especially for a multi-app repository.\n\n## Inspect current upstream behavior\n\nTreat the v1 contract as young and subject to change. Before substantial work, compare the installed or target OpenHands version with the current upstream sources when access is available:\n\n- `specs/canvas-extensions.md`\n- `src/types/canvas-extension.ts`\n- `src/components/features/canvas-extensions/canvas-extensions-runtime.tsx`\n- `src/routes/canvas-extension-page.tsx`\n- `docs/CANVAS_EXTENSIONS_TESTING.md`\n\nDo not invent planned surfaces such as conversation tabs, slots, themes, or visualizer replacement. Implement only contributions supported by the target version. Routed pages are the only implemented contribution in host API 1.\n\n## Create the app package\n\nPlace `canvas-extension.json` at the app package root. Point `entrypoint` to one self-contained browser ESM file inside that root.\n\nUse this minimal manifest shape:\n\n```json\n{\n  \"schema_version\": 1,\n  \"name\": \"example-dashboard\",\n  \"display_name\": \"Example dashboard\",\n  \"version\": \"0.1.0\",\n  \"description\": \"A backend-specific project dashboard.\",\n  \"entrypoint\": \"extension.js\",\n  \"contributes\": {\n    \"pages\": [\n      {\n        \"id\": \"dashboard\",\n        \"title\": \"Dashboard\",\n        \"path\": \"/dashboard\",\n        \"nav_label\": \"Dashboard\"\n      }\n    ]\n  }\n}\n```\n\nFor an optional package-owned managed backend, add this top-level sibling of `contributes`:\n\n```json\n\"backend\": {\n  \"schema_version\": 1,\n  \"artifacts\": {\n    \"linux-amd64\": {\n      \"path\": \"backend/linux-amd64.tar.gz\",\n      \"sha256\": \"<64 lowercase hex characters>\"\n    },\n    \"linux-arm64\": {\n      \"path\": \"backend/linux-arm64.tar.gz\",\n      \"sha256\": \"<64 lowercase hex characters>\"\n    }\n  },\n  \"argv\": [\n    \"{artifact_dir}/bin/server\",\n    \"--host=127.0.0.1\",\n    \"--port={port}\",\n    \"--data-dir={data_dir}\"\n  ],\n  \"health\": { \"path\": \"/health\" }\n}\n```\n\nThis declaration is optional. Omit it for browser-only Apps and manual/deployment-owned Sidecars. It never authorizes automatic preparation or startup. The server supports Linux amd64 and arm64 initially, verifies package-contained `.tar.gz` artifacts by SHA-256, and executes the structured argv without a shell. `argv[0]` must remain inside `{artifact_dir}`; allowed placeholders are `{artifact_dir}`, `{data_dir}`, and `{port}`.\n\nFollow these invariants:\n\n- Use lowercase letters, digits, and hyphens for app names and page IDs.\n- Use absolute kebab-case page paths with a leading slash.\n- Keep every manifest path within the app package root.\n- Give each page ID and path a unique value.\n- Register only page IDs declared in the manifest.\n- Keep the entrypoint free of unresolved bare imports and external chunks.\n- Bundle dependencies, CSS, and small assets into the entrypoint when using build tooling.\n\nAdd a concise `README.md` when the app is intended for reuse or publication. Document purpose, build command if any, output entrypoint, installation coordinate, and verification steps. Avoid adding explanatory change-log documents.\n\n## Implement activation and pages\n\nExport an `activate` function from the ESM entrypoint:\n\n```js\nexport function activate(host) {\n  if (host.apiVersion !== \"1\") {\n    throw new Error(`This app requires host API 1.`);\n  }\n\n  return host.registerPage(\"dashboard\", ({ container, path, navigate }) => {\n    const root = document.createElement(\"section\");\n    root.textContent = path ? `Nested route: ${path}` : \"Dashboard\";\n    container.append(root);\n\n    return () => root.remove();\n  });\n}\n```\n\nUse the host contract deliberately:\n\n- Read immutable metadata from `host.extension` and `host.backend`.\n- Call `host.registerPage(id, mount)` during activation.\n- Use the mount callback's `path` as the route remainder below the declared page path.\n- Treat every nested-route navigation as a fresh mount: Canvas disposes the previous mount, clears the container, and invokes the mount callback with the new remainder. DOM and framework state do not persist across route changes; keep intentional cross-route state in the URL, backend, or activation-scoped state and clean it up on deactivation.\n- Use `navigate(absoluteCanvasPath)` for Canvas-aware routing.\n- Use `host.agentServer.request({ path, method, body, headers })` for authenticated calls to the owning Agent Server.\n- Pass only root-relative request paths beginning with one `/`; never pass absolute URLs or `//` paths.\n\nPrefer [`@openhands/typescript-client`](https://github.com/OpenHands/software-agent-sdk/tree/main/clients/typescript) for bundled TypeScript integrations whenever it covers the required Agent Server API and the necessary connection inputs are available. Prefer its typed clients, models, compatibility checks, and WebSocket lifecycle over hand-written transport code. Bundle the client into the self-contained app entrypoint; never leave a bare package import or external runtime chunk.\n\nRespect the host API 1 connection boundary:\n\n- Treat `host.agentServer.request` as the portable Agent Server HTTP path; Canvas selects the active backend and supplies authentication.\n- For a managed-backend view, require the feature-detected host helper documented in `references/v1-contract.md`. The helper owns session creation, validated iframe isolation, retry/new-tab behavior, and revocation; the App never reads the app-scoped cookie or constructs the ingress URL. The ingress must be a separate browser origin from Canvas, and the host must preserve the server-returned sandbox including `allow-same-origin`.\n- Installing, enabling, activating, or mounting an App never prepares or starts a managed backend. Show the resolved revision and declaration, obtain explicit lifecycle consent, and call prepare then start with that exact revision. An update invalidates approval.\n- Do not derive an Agent Server URL from `window.location` or extract session keys from Canvas internals.\n- Do not send Automation service requests through `host.agentServer.request` unless the backend explicitly documents an Agent Server proxy for them. Automation is a separate service with deployment-provided base URL and authentication.\n- Do not open a direct Agent Server WebSocket from a portable v1 app. The host currently exposes neither the owning server origin nor a WebSocket/auth capability. Poll through `host.agentServer.request`, add a backend-owned bridge, or feature-detect a future host subscription API.\n- Use the TypeScript client's Agent Server WebSocket support in trusted standalone or future host-enabled contexts, and stop it during disposal. Do not treat the Agent Server client as an Automation service client.\n\nReturn cleanup from every layer that creates effects:\n\n- Return the unregister function or an activation disposer from `activate`.\n- Return a mount disposer for DOM nodes, timers, listeners, observers, subscriptions, and outstanding state.\n- Make async work disposal-aware so late responses cannot mutate an unmounted page.\n- Remove injected styles when the page unmounts.\n\nAssume activation, mounting, and disposal may happen repeatedly during hot enable/disable, updates, backend switches, reconnects, and route changes.\n\n## Build a production-quality page\n\nRender within the supplied `container`; do not replace unrelated Canvas DOM. Scope CSS under an app-specific root class. Prefer Canvas CSS variables with sensible fallbacks rather than copying host implementation classes.\n\nProvide:\n\n- semantic structure and headings inside the supplied container. Canvas already owns the outer `<main aria-label={page title}>`, so do not add a nested `main` or duplicate page landmark label;\n- keyboard-operable controls and visible focus;\n- responsive behavior for narrow layouts;\n- loading, empty, stale, and error states;\n- reduced-motion handling for animation;\n- text-safe rendering through DOM APIs or escaping rather than untrusted `innerHTML`;\n- clear handling for malformed or partial Agent Server responses.\n\nAvoid global event handlers, prototype changes, global CSS selectors, and ambient state unless unavoidable. Same-realm execution means these effects have full Canvas authority and cleanup is only best-effort.\n\n## Add tests\n\nTest real app code with a DOM environment and a small Canvas Extensions API host test double. Test at minimum:\n\n1. `activate` registers every declared page exactly once.\n2. The mount renders its initial state.\n3. Agent Server requests use the expected root-relative path and method.\n4. Nested navigation disposes the prior mount and remounts with the correct route remainder; test any intentionally preserved state explicitly.\n5. The mount disposer removes DOM and stops effects.\n6. The activation disposer unregisters contributions.\n7. Unsupported host API versions fail clearly when compatibility is checked.\n8. Network and malformed-response errors render safely.\n\nUse the repository's existing test infrastructure. Do not introduce a new framework when adequate tests already exist. For dependency-free fixtures, Vitest with a DOM environment matches the upstream example, but it is not part of the Canvas Extensions API runtime contract.\n\n## Validate the package\n\nRun the bundled validator before reporting completion:\n\n```sh\nnode /path/to/canvas-extension-api/scripts/validate-extension.mjs /path/to/app-package\n```\n\nThen run the target repository's formatter, linter, tests, and build. Inspect the final entrypoint rather than assuming the bundler configuration worked:\n\n- confirm the file exists at the manifest path;\n- confirm it exports `activate`;\n- reject bare imports and dynamic external chunks;\n- confirm CSS and required small assets are bundled or embedded;\n- confirm the output runs as browser ESM without Node globals.\n\nTreat validator warnings as prompts for inspection, not proof of invalidity. The helper uses conservative static checks and cannot replace loading the app bundle in Canvas.\n\n## Install and verify safely\n\nInstall only when requested. Installation and enablement are separate product actions: installation must leave the app disabled, and enabling executes trusted same-realm code. Managed-backend preparation and startup are additional explicit actions tied to the resolved revision; installation, enablement, activation, and ordinary page mounts never execute backend code.\n\nFor a backend-local app, install the path as interpreted on the Agent Server machine. For a Git-hosted app, provide `source`, optional `ref`, and optional `repo_path`. Never assume a frontend-local path exists inside a remote or containerized backend.\n\nFor multiple apps in one repository, produce an install matrix listing app name, manifest directory, source, ref, and `repo_path`. Submit one Add app operation per row. For remote repositories, omit `repo_path` only when the selected app lives at the repository root. For backend-local sources, make `source` the selected app package directory. Do not claim that selecting a repository root installs nested apps.\n\nValidate and test every app package independently, then run shared repository checks once. Report partial failures by app name rather than treating one passing app package as validation of the entire repository.\n\nVerify the lifecycle in Canvas:\n\n1. Install and confirm the inventory entry is disabled.\n2. Review source, revision, manifest metadata, and contributions.\n3. Enable and accept the trusted-code disclosure: “This app runs trusted JavaScript inside Agent Canvas and can make authenticated requests to the active Agent Server. Review its source and revision before enabling it.”\n4. Open the navigation item and exercise root and nested routes.\n5. Disable and confirm navigation and mounted UI disappear.\n6. Re-enable without restarting Canvas.\n7. Switch backend or reconnect when relevant and confirm isolation.\n8. Uninstall only when requested.\n\nDo not enable, uninstall, publish, push, or open a pull request without the user's authorization.\n\n## Report completion\n\nSummarize:\n\n- app location and contributed pages;\n- manifest schema and host API targeted;\n- build output and validation results;\n- tests run and their results;\n- installation status, explicitly stating whether it remains disabled;\n- remaining limitations tied to the current v1 ABI.\n\n## Resources\n\n- `references/v1-contract.md` - exact manifest, host API, lifecycle, routing, trust, and current limitations.\n- `references/connections.md` - Agent Server HTTP, Automation service, WebSocket, and TypeScript client connection guidance.\n- `references/testing-and-installation.md` - test strategy, manual Canvas workflow, and installation coordinates.\n- `references/packaging-recipes.md` - one-file Vite, CSS, assets, Workers, and WASM rules.\n- `references/backend-safety.md` - authenticated requests, command safety, persistence, and prerequisite onboarding.\n- `references/acceptance-checklist.md` - automated checks and the local install/enable/reload lifecycle.\n- `scripts/validate-extension.mjs` - dependency-free static artifact validator for an App package directory.",
+    "content": "# Canvas Extensions API\n\nBuild and validate OpenHands Apps with the Canvas Extensions API, targeting the currently implemented manifest schema 1 and host API 1 routed-page ABI.\n\nUse the naming layers consistently:\n\n- **OpenHands Apps** - customer-facing category for interfaces people discover, install, enable, and open.\n- **Apps for Agent Canvas** - product phrasing that clarifies where apps run.\n- **Canvas Extensions API** - developer platform used to build apps.\n- **Canvas extension package** - technical artifact containing `canvas-extension.json` and its entrypoint.\n- **OpenHands Extensions** - ecosystem and repository umbrella for apps, skills, plugins, automations, and integrations.\n\nUse current product labels in user-facing instructions: **Apps for Agent Canvas**, **Add app**, **Installed apps**, **App source**, **Enable trusted app**, and **Build an app**. Keep technical identifiers such as `canvas-extension.json`, `/api/canvas-extensions/*`, `host.extension`, and `/extensions/*` unchanged unless the target implementation changes them.\n\nTreat apps as trusted, same-realm browser code owned by the active Agent Server. Keep the categories distinct: apps extend what people can do in Agent Canvas, plugins extend agent runtime capabilities, and skills provide agent instructions and knowledge.\n\n\n## Prefer the proven App authoring loop\n\nTreat an App as one authenticated browser dependency graph that Canvas imports from a Blob URL. Do not build a hosted SPA: the production result must be exactly one self-contained browser ESM entrypoint that exports `activate(host)`. Always ship this UI package even when it uses an optional package-owned managed backend or a manual/deployment-owned Sidecar. Make the App page the guided UI for service setup after the App is opened. Never treat a service as another browser chunk or an automatic extension install hook.\n\nFor a new App, create an independent package in the target repository and implement its own UI, tests, and build tooling. Follow the Vite library-build reference in `references/packaging-recipes.md`; do not copy a shared starter or introduce a repository-wide runtime/workspace unless the target repository explicitly requires it.\n\nKeep all source, scripts, dependencies, tests, and checked-in `extension.js` inside the App package. Implement one declared page with explicit root, nested, and unknown-route behavior. Inject scoped CSS per mount and clean it up with framework roots, requests, listeners, timers, Workers, and object URLs. Build validation must verify `dist/extension.js` before synchronizing it to the App root. Do not synchronize an unverified artifact. Use `CHROME_PATH` when the Chrome executable is elsewhere.\n\nFor an existing App, run the reusable static gate before and after its own checks:\n\n```sh\nnode /path/to/canvas-extension-api/scripts/validate-extension.mjs /path/to/app\nnode /path/to/canvas-extension-api/scripts/validate-extension.mjs /path/to/app --dist --marker <required-feature-marker>\n```\n\nTreat the static validator as a gate, not a replacement for the browser Blob smoke test. Read `references/packaging-recipes.md` before adding CSS, raw assets, dynamic modules, Workers, or WASM. Read `references/backend-safety.md` before any Agent Server integration or persistence. Read `references/sidecar-pattern.md` before designing a separately installed service or its onboarding. Read `references/acceptance-checklist.md` before reporting local Canvas compatibility.\n\n## Establish the target\n\nStart by locating the target directory instead of assuming the current workspace. Inspect repository instructions, existing package management, build tooling, tests, and git status before editing.\n\nMake an early architecture decision: browser-only App, Agent Server-integrated App, package-owned managed-backend App, manual/deployment-owned Sidecar App, or explicitly deployment-specific App. Keep the portable host API 1 surface separate from optional Agent Server/host capabilities and deployment-owned behavior.\n\nUse the package-owned managed-backend path only when the target stack includes the lifecycle contract from [software-agent-sdk PR #5270](https://github.com/OpenHands/software-agent-sdk/pull/5270) at `ac7b322ddf7d2e0e90a3643c5e26d848236af9a3`, the bridge contract from [PR #5272](https://github.com/OpenHands/software-agent-sdk/pull/5272) at `6d9c82973e765cce4843d6a2fb52f634efa64293`, and the host version named in `references/v1-contract.md`. Until a release containing both SDK PRs lands, those exact revisions are the minimum Agent Server implementation. Feature-detect `canvas_app_backend_bridge_v1` and `app_backend_ingress_url` through `GET /server_info`; absence is an actionable unsupported state. Do not convert manual Sidecars into managed backends unless the App owns checksum-pinned artifacts for every supported platform.\n\nClarify only choices that materially affect implementation:\n\n- app purpose and page behavior;\n- target repository and subdirectory;\n- dependency-free JavaScript versus a bundled TypeScript/framework project;\n- Agent Server endpoints or host metadata required;\n- whether to build only, install locally, or prepare publication instructions;\n- for a Sidecar: execution location, owner, connection route, secrets and data, lifecycle actions, and portability across Agent Canvas deployments.\n\nDefault to one app with one routed page when requirements are otherwise clear. Keep the first implementation small and dependency-free unless the requested UI clearly benefits from a framework or the repository already has a bundler.\n\nWhen creating multiple Apps in one repository, give every App an independent package root containing its own `canvas-extension.json`, entrypoint, version, tests, README, and build tooling. Do not introduce a monorepo, shared runtime, or common build foundation unless the target repository explicitly requires one. Keep app manifest names globally distinct within the Agent Server installation.\n\nTreat installation as one app per request. The current Customize -> Apps flow accepts one `source`, optional `ref`, and optional `repo_path`; it does not recursively discover or bulk-install every manifest in a repository. For a remote repository, add each app separately using the same source/ref and its own `repo_path`. For a backend-local source, select each app package directory as the source path.\n\nRead `references/v1-contract.md` before implementing unfamiliar Canvas Extensions API behavior. Read `references/connections.md` before connecting to Agent Server, the Automation service, or WebSocket endpoints. Read `references/sidecar-pattern.md` before proposing a Sidecar bridge, onboarding, or operator action. Read `references/testing-and-installation.md` before installing or testing inside Agent Canvas, especially for a multi-app repository.\n\n## Inspect current upstream behavior\n\nTreat the v1 contract as young and subject to change. Before substantial work, compare the installed or target OpenHands version with the current upstream sources when access is available:\n\n- `specs/canvas-extensions.md`\n- `src/types/canvas-extension.ts`\n- `src/components/features/canvas-extensions/canvas-extensions-runtime.tsx`\n- `src/routes/canvas-extension-page.tsx`\n- `docs/CANVAS_EXTENSIONS_TESTING.md`\n\nDo not invent planned surfaces such as conversation tabs, slots, themes, or visualizer replacement. Implement only contributions supported by the target version. Routed pages are the only implemented contribution in host API 1.\n\n## Create the app package\n\nPlace `canvas-extension.json` at the app package root. Point `entrypoint` to one self-contained browser ESM file inside that root.\n\nUse this minimal manifest shape:\n\n```json\n{\n  \"schema_version\": 1,\n  \"name\": \"example-dashboard\",\n  \"display_name\": \"Example dashboard\",\n  \"version\": \"0.1.0\",\n  \"description\": \"A backend-specific project dashboard.\",\n  \"entrypoint\": \"extension.js\",\n  \"contributes\": {\n    \"pages\": [\n      {\n        \"id\": \"dashboard\",\n        \"title\": \"Dashboard\",\n        \"path\": \"/dashboard\",\n        \"nav_label\": \"Dashboard\"\n      }\n    ]\n  }\n}\n```\n\nFor an optional package-owned managed backend, add this top-level sibling of `contributes`:\n\n```json\n\"backend\": {\n  \"schema_version\": 1,\n  \"artifacts\": {\n    \"linux-amd64\": {\n      \"path\": \"backend/linux-amd64.tar.gz\",\n      \"sha256\": \"<64 lowercase hex characters>\"\n    },\n    \"linux-arm64\": {\n      \"path\": \"backend/linux-arm64.tar.gz\",\n      \"sha256\": \"<64 lowercase hex characters>\"\n    }\n  },\n  \"argv\": [\n    \"{artifact_dir}/bin/server\",\n    \"--host=127.0.0.1\",\n    \"--port={port}\",\n    \"--data-dir={data_dir}\"\n  ],\n  \"health\": { \"path\": \"/health\" }\n}\n```\n\nThis declaration is optional. Omit it for browser-only Apps and manual/deployment-owned Sidecars. It never authorizes automatic preparation or startup. The server supports Linux amd64 and arm64 initially, verifies package-contained `.tar.gz` artifacts by SHA-256, and executes the structured argv without a shell. `argv[0]` must remain inside `{artifact_dir}`; allowed placeholders are `{artifact_dir}`, `{data_dir}`, and `{port}`.\n\nFollow these invariants:\n\n- Use lowercase letters, digits, and hyphens for app names and page IDs.\n- Use absolute kebab-case page paths with a leading slash.\n- Keep every manifest path within the app package root.\n- Give each page ID and path a unique value.\n- Register only page IDs declared in the manifest.\n- Keep the entrypoint free of unresolved bare imports and external chunks.\n- Bundle dependencies, CSS, and small assets into the entrypoint when using build tooling.\n\nAdd a concise `README.md` when the app is intended for reuse or publication. Document purpose, build command if any, output entrypoint, installation coordinate, and verification steps. Avoid adding explanatory change-log documents.\n\n## Implement activation and pages\n\nExport an `activate` function from the ESM entrypoint:\n\n```js\nexport function activate(host) {\n  if (host.apiVersion !== \"1\") {\n    throw new Error(`This app requires host API 1.`);\n  }\n\n  return host.registerPage(\"dashboard\", ({ container, path, navigate }) => {\n    const root = document.createElement(\"section\");\n    root.textContent = path ? `Nested route: ${path}` : \"Dashboard\";\n    container.append(root);\n\n    return () => root.remove();\n  });\n}\n```\n\nUse the host contract deliberately:\n\n- Read immutable metadata from `host.extension` and `host.backend`.\n- Call `host.registerPage(id, mount)` during activation.\n- Use the mount callback's `path` as the route remainder below the declared page path.\n- Treat every nested-route navigation as a fresh mount: Canvas disposes the previous mount, clears the container, and invokes the mount callback with the new remainder. DOM and framework state do not persist across route changes; keep intentional cross-route state in the URL, backend, or activation-scoped state and clean it up on deactivation.\n- Use `navigate(absoluteCanvasPath)` for Canvas-aware routing.\n- Use `host.agentServer.request({ path, method, body, headers })` for authenticated calls to the owning Agent Server.\n- Pass only root-relative request paths beginning with one `/`; never pass absolute URLs or `//` paths.\n\nPrefer [`@openhands/typescript-client`](https://github.com/OpenHands/software-agent-sdk/tree/main/clients/typescript) for bundled TypeScript integrations whenever it covers the required Agent Server API and the necessary connection inputs are available. Prefer its typed clients, models, compatibility checks, and WebSocket lifecycle over hand-written transport code. Bundle the client into the self-contained app entrypoint; never leave a bare package import or external runtime chunk.\n\nRespect the host API 1 connection boundary:\n\n- Treat `host.agentServer.request` as the portable Agent Server HTTP path; Canvas selects the active backend and supplies authentication.\n- For a managed-backend view, require the feature-detected host helper documented in `references/v1-contract.md`. The helper owns session creation, validated iframe isolation, retry/new-tab behavior, and revocation; the App never reads the app-scoped cookie or constructs the ingress URL. The ingress must be a separate browser origin from Canvas, and the host must preserve the server-returned sandbox including `allow-same-origin`.\n- Installing, enabling, activating, or mounting an App never prepares or starts a managed backend. Show the resolved revision and declaration, obtain explicit lifecycle consent, and call prepare then start with that exact revision. An update invalidates approval.\n- Do not derive an Agent Server URL from `window.location` or extract session keys from Canvas internals.\n- Do not send Automation service requests through `host.agentServer.request` unless the backend explicitly documents an Agent Server proxy for them. Automation is a separate service with deployment-provided base URL and authentication.\n- Do not open a direct Agent Server WebSocket from a portable v1 app. The host currently exposes neither the owning server origin nor a WebSocket/auth capability. Poll through `host.agentServer.request`, add a backend-owned bridge, or feature-detect a future host subscription API.\n- Use the TypeScript client's Agent Server WebSocket support in trusted standalone or future host-enabled contexts, and stop it during disposal. Do not treat the Agent Server client as an Automation service client.\n\nReturn cleanup from every layer that creates effects:\n\n- Return the unregister function or an activation disposer from `activate`.\n- Return a mount disposer for DOM nodes, timers, listeners, observers, subscriptions, and outstanding state.\n- Make async work disposal-aware so late responses cannot mutate an unmounted page.\n- Remove injected styles when the page unmounts.\n\nAssume activation, mounting, and disposal may happen repeatedly during hot enable/disable, updates, backend switches, reconnects, and route changes.\n\n## Build a production-quality page\n\nRender within the supplied `container`; do not replace unrelated Canvas DOM. Scope CSS under an app-specific root class. Prefer Canvas CSS variables with sensible fallbacks rather than copying host implementation classes.\n\nRead `references/native-design.md` before styling an App page. It covers the core rule (reuse tokens, not host internals), the three implementation paths (dependency-free, Tailwind-bundled, existing CSS), the Tailwind v4 theme mapping to host variables, layout and density conventions, copy-ready component recipes, the raw scoped CSS alternative, and a mount-safe style helper. Treat it as the authoritative design reference for Apps.\n\nProvide:\n\n- semantic structure and headings inside the supplied container. Canvas already owns the outer `<main aria-label={page title}>`, so do not add a nested `main` or duplicate page landmark label;\n- keyboard-operable controls and visible focus;\n- responsive behavior for narrow layouts;\n- loading, empty, stale, and error states;\n- reduced-motion handling for animation;\n- text-safe rendering through DOM APIs or escaping rather than untrusted `innerHTML`;\n- clear handling for malformed or partial Agent Server responses.\n\nAvoid global event handlers, prototype changes, global CSS selectors, and ambient state unless unavoidable. Same-realm execution means these effects have full Canvas authority and cleanup is only best-effort.\n\n## Add tests\n\nTest real app code with a DOM environment and a small Canvas Extensions API host test double. Test at minimum:\n\n1. `activate` registers every declared page exactly once.\n2. The mount renders its initial state.\n3. Agent Server requests use the expected root-relative path and method.\n4. Nested navigation disposes the prior mount and remounts with the correct route remainder; test any intentionally preserved state explicitly.\n5. The mount disposer removes DOM and stops effects.\n6. The activation disposer unregisters contributions.\n7. Unsupported host API versions fail clearly when compatibility is checked.\n8. Network and malformed-response errors render safely.\n\nUse the repository's existing test infrastructure. Do not introduce a new framework when adequate tests already exist. For dependency-free fixtures, Vitest with a DOM environment matches the upstream example, but it is not part of the Canvas Extensions API runtime contract.\n\n## Validate the package\n\nRun the bundled validator before reporting completion:\n\n```sh\nnode /path/to/canvas-extension-api/scripts/validate-extension.mjs /path/to/app-package\n```\n\nThen run the target repository's formatter, linter, tests, and build. Inspect the final entrypoint rather than assuming the bundler configuration worked:\n\n- confirm the file exists at the manifest path;\n- confirm it exports `activate`;\n- reject bare imports and dynamic external chunks;\n- confirm CSS and required small assets are bundled or embedded;\n- confirm the output runs as browser ESM without Node globals.\n\nTreat validator warnings as prompts for inspection, not proof of invalidity. The helper uses conservative static checks and cannot replace loading the app bundle in Canvas.\n\n## Install and verify safely\n\nInstall only when requested. Installation and enablement are separate product actions: installation must leave the app disabled, and enabling executes trusted same-realm code. Managed-backend preparation and startup are additional explicit actions tied to the resolved revision; installation, enablement, activation, and ordinary page mounts never execute backend code.\n\nFor a backend-local app, install the path as interpreted on the Agent Server machine. For a Git-hosted app, provide `source`, optional `ref`, and optional `repo_path`. Never assume a frontend-local path exists inside a remote or containerized backend.\n\nFor multiple apps in one repository, produce an install matrix listing app name, manifest directory, source, ref, and `repo_path`. Submit one Add app operation per row. For remote repositories, omit `repo_path` only when the selected app lives at the repository root. For backend-local sources, make `source` the selected app package directory. Do not claim that selecting a repository root installs nested apps.\n\nValidate and test every app package independently, then run shared repository checks once. Report partial failures by app name rather than treating one passing app package as validation of the entire repository.\n\nVerify the lifecycle in Canvas:\n\n1. Install and confirm the inventory entry is disabled.\n2. Review source, revision, manifest metadata, and contributions.\n3. Enable and accept the trusted-code disclosure: “This app runs trusted JavaScript inside Agent Canvas and can make authenticated requests to the active Agent Server. Review its source and revision before enabling it.”\n4. Open the navigation item and exercise root and nested routes.\n5. Disable and confirm navigation and mounted UI disappear.\n6. Re-enable without restarting Canvas.\n7. Switch backend or reconnect when relevant and confirm isolation.\n8. Uninstall only when requested.\n\nDo not enable, uninstall, publish, push, or open a pull request without the user's authorization.\n\n## Report completion\n\nSummarize:\n\n- app location and contributed pages;\n- manifest schema and host API targeted;\n- build output and validation results;\n- tests run and their results;\n- installation status, explicitly stating whether it remains disabled;\n- remaining limitations tied to the current v1 ABI.\n\n## Resources\n\n- `references/v1-contract.md` - exact manifest, host API, lifecycle, routing, trust, and current limitations.\n- `references/connections.md` - Agent Server HTTP, Automation service, WebSocket, and TypeScript client connection guidance.\n- `references/testing-and-installation.md` - test strategy, manual Canvas workflow, and installation coordinates.\n- `references/packaging-recipes.md` - one-file Vite, CSS, assets, Workers, and WASM rules.\n- `references/backend-safety.md` - authenticated requests, command safety, persistence, and prerequisite onboarding.\n- `references/native-design.md` - native Agent Canvas styling: token reuse, Tailwind mapping, layout, component recipes, scoped CSS, and style injection.\n- `references/acceptance-checklist.md` - automated checks and the local install/enable/reload lifecycle.\n- `scripts/validate-extension.mjs` - dependency-free static artifact validator for an App package directory.",
     "category": "agent-authoring",
     "defaultEnabled": true
   },

openhands_extensions-0.28.0/.release-please-manifest.json

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