@openhands/extensions 0.27.0 → 0.29.0

package/plugins/vulnerability-remediation/skills/github/scripts/agent_conversation.py

@@ -32,6 +32,11 @@ _CLOUD_START_GRACE_SECONDS = 10 * 60
 # How long to wait for a paused conversation's sandbox to come back up.
 _CLOUD_RESUME_TIMEOUT_SECONDS = 120
 _CLOUD_POLL_SECONDS = 3
+# How many times a matched delivery whose conversation ended in ERROR is sent
+# again. The delivery key never changes for a stable subject, so without a
+# retry its work is stranded; without a bound, a conversation that fails the
+# same way every time would be re-run on every scan.
+_MAX_ERROR_RETRIES = 2
 
 
 def _register_tools() -> None:
@@ -204,14 +209,23 @@ class AgentConversationDispatcher:
 
         same_delivery = record.get("delivery") == delivery
         same_head = bool(head) and record.get("head") == head
+        # Error retries count against one delivery; a new delivery starts over.
+        error_retries = int(record.get("error_retries") or 0) if same_delivery else 0
+        can_retry = error_retries < _MAX_ERROR_RETRIES
 
         if self._cloud:
             disposition, conversation_id = self._deliver_cloud(
-                record, conversation_id, subject, prompt, same_delivery, same_head
+                record,
+                conversation_id,
+                subject,
+                prompt,
+                same_delivery,
+                same_head,
+                can_retry,
             )
         else:
             disposition = self._deliver_local(
-                conversation_id, prompt, same_delivery, same_head
+                conversation_id, prompt, same_delivery, same_head, can_retry
             )
 
         if disposition in ("deduplicated", "in_progress"):
@@ -228,6 +242,10 @@ class AgentConversationDispatcher:
         }
         if disposition == "created" and self._cloud:
             new_record["started_at"] = time.time()
+        if disposition == "retried":
+            error_retries += 1
+        if error_retries:
+            new_record["error_retries"] = error_retries
         _kv_request(state_key, "PUT", new_record)
         return {
             "disposition": disposition,
@@ -235,7 +253,14 @@ class AgentConversationDispatcher:
         }
 
     def _deliver_cloud(
-        self, record, conversation_id, subject, prompt, same_delivery, same_head
+        self,
+        record,
+        conversation_id,
+        subject,
+        prompt,
+        same_delivery,
+        same_head,
+        can_retry,
     ):
         """Deliver through the OpenHands API; return the disposition and the id.
 
@@ -272,11 +297,21 @@ class AgentConversationDispatcher:
             if status in ("idle", "paused"):
                 self._cloud.run(conversation)
                 return "resumed", current_id
+            if status == "error" and can_retry:
+                # The delivery matched but its conversation died before the work
+                # finished, so send the revision again rather than strand it.
+                # The API reports an execution status only while the sandbox
+                # runs, so an errored conversation whose sandbox was already
+                # paused is not seen here and keeps reporting deduplicated.
+                self._cloud.send(conversation, prompt)
+                return "retried", current_id
             return "deduplicated", current_id
         self._cloud.send(conversation, prompt)
         return "resumed", current_id
 
-    def _deliver_local(self, conversation_id, prompt, same_delivery, same_head) -> str:
+    def _deliver_local(
+        self, conversation_id, prompt, same_delivery, same_head, can_retry
+    ) -> str:
         if self._workspace is None:
             raise RuntimeError("AgentConversationDispatcher must be used as a context")
 
@@ -321,6 +356,18 @@ class AgentConversationDispatcher:
                     ):
                         conversation.update_secrets(self._secrets)
                         conversation.run(blocking=False)
+                    elif (
+                        conversation.state.execution_status
+                        == ConversationExecutionStatus.ERROR
+                        and can_retry
+                    ):
+                        # The delivery matched but its conversation died before
+                        # the work finished, so send the revision again rather
+                        # than strand it.
+                        conversation.update_secrets(self._secrets)
+                        conversation.send_message(prompt)
+                        conversation.run(blocking=False)
+                        disposition = "retried"
                     else:
                         disposition = "deduplicated"
                 else:

package/pyproject.toml

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

package/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.27.0"  # x-release-please-version
+_FALLBACK_VERSION = "0.29.0"  # x-release-please-version
 
 try:
     __version__: str = version("openhands-extensions")

package/scripts/sync_openhands_sdk_skill.py

@@ -25,6 +25,7 @@ from pathlib import Path
 
 SKILL_PATH = Path(__file__).resolve().parent.parent / "skills" / "openhands-sdk" / "SKILL.md"
 LLMS_TXT_URL = "https://docs.openhands.dev/llms.txt"
+SDK_URL_PREFIX = "https://docs.openhands.dev/sdk/"
 GH_API = "https://api.github.com/repos/OpenHands/software-agent-sdk/contents/examples"
 GH_RAW = "https://raw.githubusercontent.com/OpenHands/software-agent-sdk/main"
 GH_BROWSE = "https://github.com/OpenHands/software-agent-sdk/blob/main/examples"
@@ -90,18 +91,20 @@ def _fetch_or(url: str, fallback, **kw):
 # -- llms.txt parsing --
 
 def parse_sdk_entries(llms_txt: str) -> list[dict]:
-    """Extract entries from the 'OpenHands Software Agent SDK' section."""
-    entries, in_section = [], False
-    for line in llms_txt.splitlines():
-        stripped = line.strip()
-        if stripped == "## OpenHands Software Agent SDK":
-            in_section = True
-            continue
-        if in_section and line.startswith("## "):
-            break
-        if in_section and (m := _ENTRY_RE.match(stripped)):
-            entries.append(m.groupdict())
-    return entries
+    """Extract entries for the OpenHands Software Agent SDK.
+
+    The docs index (llms.txt) no longer groups entries under an
+    "OpenHands Software Agent SDK" heading, so select entries by their
+    canonical URL prefix instead. Sort by title (case-insensitively) to
+    keep the generated skill stable across runs.
+    """
+    entries = [
+        m.groupdict()
+        for line in llms_txt.splitlines()
+        if (m := _ENTRY_RE.match(line.strip()))
+        and m.group("url").startswith(SDK_URL_PREFIX)
+    ]
+    return sorted(entries, key=lambda e: e["title"].lower())
 
 
 # -- content builders --
@@ -123,7 +126,7 @@ def build_classes_table(entries: list[dict]) -> str:
 def build_api_refs(entries: list[dict]) -> str:
     return ", ".join(
         f"[`{e['title']}`]({e['url']})"
-        for e in entries if "/api-reference/" in e["url"]
+        for e in entries if "/sdk/api-reference/" in e["url"]
     )
 
 

package/skills/azure-devops/README.md

@@ -11,6 +11,8 @@ This skill is activated by the following keywords:
 
 ## Details
 
+Use authenticated Azure DevOps MCP tools first when they are available in the agent's environment. Detect the connection through tool availability rather than a particular server name. Fall back to the documented `AZURE_DEVOPS_TOKEN` and direct API flow when those tools are unavailable or raw API or `curl` access is explicitly needed.
+
 You have access to an environment variable, `AZURE_DEVOPS_TOKEN`, which allows you to interact with
 the Azure DevOps API.
 
@@ -52,4 +54,4 @@ Common API endpoints:
 - List repositories: `https://dev.azure.com/{organization}/{project}/_apis/git/repositories?api-version=7.1`
 - Get repository details: `https://dev.azure.com/{organization}/{project}/_apis/git/repositories/{repositoryId}?api-version=7.1`
 - List pull requests: `https://dev.azure.com/{organization}/{project}/_apis/git/pullrequests?api-version=7.1`
-- Create pull request: `https://dev.azure.com/{organization}/{project}/_apis/git/repositories/{repositoryId}/pullrequests?api-version=7.1` (POST)
+- Create pull request: `https://dev.azure.com/{organization}/{project}/_apis/git/repositories/{repositoryId}/pullrequests?api-version=7.1` (POST)

package/skills/azure-devops/SKILL.md

@@ -6,6 +6,10 @@ triggers:
 - azure
 ---
 
+## Connection selection
+
+Use authenticated Azure DevOps MCP tools first when they are available in the agent's environment. Detect this by tool availability, without depending on a particular MCP server name. Use the token and direct API instructions below only when Azure DevOps MCP tools are unavailable or when raw API or `curl` access is explicitly needed.
+
 You have access to an environment variable, `AZURE_DEVOPS_TOKEN`, which allows you to interact with
 the Azure DevOps API.
 

package/skills/bitbucket/README.md

@@ -3,6 +3,8 @@
 Bitbucket integration **hub** skill. It detects whether the repository is on Bitbucket
 Cloud or Bitbucket Data Center and directs the agent to the matching detailed skill.
 
+Authenticated Bitbucket MCP tools are preferred when available, detected generically by tool availability rather than a particular server name. The hub still routes to Cloud or Data Center, and the documented token and direct API paths remain the fallback when MCP tools are unavailable or raw API or `curl` access is explicitly needed.
+
 ## Triggers
 
 This skill is activated by the following keywords:
@@ -30,4 +32,4 @@ when the words "data center" never appear. It then:
 The hub also carries a small quick-reference table as a fallback in case the detailed skill
 cannot be loaded.
 
-See [`SKILL.md`](SKILL.md) for the full content.
+See [`SKILL.md`](SKILL.md) for the full content.

package/skills/bitbucket/SKILL.md

@@ -5,6 +5,8 @@ triggers:
 - bitbucket
 ---
 
+Use authenticated Bitbucket MCP tools first when they are available in the agent's environment. Detect this by tool availability, without depending on a particular MCP server name. Still identify Cloud versus Data Center and load the matching detailed skill. Use the token and direct API instructions only when Bitbucket MCP tools are unavailable or when raw API or `curl` access is explicitly needed.
+
 You are working with **Bitbucket**, which ships as two distinct products that behave
 differently:
 
@@ -19,7 +21,7 @@ detailed skill for full instructions.
 
 ## Step 1 — Detect which Bitbucket you are on
 
-Check which token environment variable is present. Environment variable names are
+First use the repository host or available Bitbucket MCP tool context to identify the product. For the token fallback, check which token environment variable is present. Environment variable names are
 case-sensitive, so look for it case-insensitively:
 
 ```bash
@@ -53,4 +55,4 @@ Bitbucket API (not a web browser) and always use the listed PR tool to open a pu
 | Host | `bitbucket.org` | self-hosted domain |
 | REST API base | `https://api.bitbucket.org/2.0` | `https://<host>/rest/api/1.0` |
 | Repository identifier | `workspace/repo_slug` | `PROJECT/repo_slug` (project key) |
-| Pull request tool | `create_bitbucket_pr` | `create_bitbucket_data_center_pr` |
+| Pull request tool | `create_bitbucket_pr` | `create_bitbucket_data_center_pr` |

package/skills/bitbucket-cloud/README.md

@@ -11,5 +11,7 @@ it detects a Bitbucket Cloud environment (i.e. `BITBUCKET_TOKEN` is set).
 
 ## Details
 
+Use authenticated Bitbucket Cloud MCP tools first when they are available, detected by tool availability rather than a particular server name. Fall back to the documented `BITBUCKET_TOKEN` and direct REST API flow when those tools are unavailable or raw API or `curl` access is explicitly needed.
+
 See [`SKILL.md`](SKILL.md) for the full content, including authenticated git remote
 construction and pull request instructions.

package/skills/bitbucket-cloud/SKILL.md

@@ -3,6 +3,8 @@ name: bitbucket-cloud
 description: Bitbucket Cloud (bitbucket.org) specifics — authenticate with BITBUCKET_TOKEN, use the REST API v2, workspace/repo_slug repositories, and the create_bitbucket_pr tool. Loaded on demand by the bitbucket skill once a Cloud environment is detected.
 ---
 
+Use authenticated Bitbucket Cloud MCP tools first when they are available in the agent's environment. Detect this by tool availability, without depending on a particular MCP server name. Use the token and direct REST API instructions below only when those tools are unavailable or when raw API or `curl` access is explicitly needed.
+
 You are working with **Bitbucket Cloud** (`bitbucket.org`). You have access to an
 environment variable, `BITBUCKET_TOKEN`, which allows you to interact with the Bitbucket
 Cloud API.

package/skills/bitbucket-data-center/README.md

@@ -12,6 +12,8 @@ it detects a Bitbucket Data Center environment (i.e. `BITBUCKET_DATA_CENTER_TOKE
 
 ## Details
 
+Use authenticated Bitbucket Data Center MCP tools first when they are available, detected by tool availability rather than a particular server name. Fall back to the documented `BITBUCKET_DATA_CENTER_TOKEN` and direct REST API flow when those tools are unavailable or raw API or `curl` access is explicitly needed.
+
 See [`SKILL.md`](SKILL.md) for the full content, including authenticated `scm/` git remote
 construction and pull request instructions. Note the key differences from Bitbucket Cloud:
 the REST API is version `1.0` under `https://{domain}/rest/api/1.0`, repositories are

package/skills/bitbucket-data-center/SKILL.md

@@ -3,6 +3,8 @@ name: bitbucket-data-center
 description: Bitbucket Data Center (self-hosted Bitbucket Server) specifics — authenticate with BITBUCKET_DATA_CENTER_TOKEN, use the REST API 1.0, PROJECT/repo_slug repositories, scm/ git remotes, and the create_bitbucket_data_center_pr tool. Loaded on demand by the bitbucket skill once a Data Center environment is detected.
 ---
 
+Use authenticated Bitbucket Data Center MCP tools first when they are available in the agent's environment. Detect this by tool availability, without depending on a particular MCP server name. Use the token and direct REST API instructions below only when those tools are unavailable or when raw API or `curl` access is explicitly needed.
+
 You are working with **Bitbucket Data Center** (self-hosted Bitbucket Server). You have
 access to an environment variable, `BITBUCKET_DATA_CENTER_TOKEN`, which contains a basic
 auth token in the format `username:your-token` that allows you to interact with the git

package/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.

package/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.

package/skills/github/README.md

@@ -11,6 +11,8 @@ This skill is activated by the following keywords:
 
 ## Details
 
+Use authenticated GitHub MCP tools first when they are available in the agent's environment. Detect the connection through tool availability rather than a particular server name. Fall back to the documented `GITHUB_TOKEN` and direct API flow when those tools are unavailable or raw API or `curl` access is explicitly needed.
+
 You have access to an environment variable, `GITHUB_TOKEN`, which allows you to interact with
 the GitHub API.
 
@@ -39,4 +41,6 @@ Here are some instructions for pushing, but ONLY do this if the user asks you to
 ```bash
 git remote -v && git branch # to find the current org, repo and branch
 git checkout -b create-widget && git add . && git commit -m "Create widget" && git push -u origin create-widget
-```
+```
+
+When asked to merge a pull request, the skill uses GitHub's async merge API (`PUT /repos/{owner}/{repo}/pulls/{pull_number}/merge-async`, then poll the returned UUID). It supports stacked PRs and merge queues. Docs: https://docs.github.com/en/rest/pulls/pulls#merge-a-pull-request-asynchronously

package/skills/github/SKILL.md

@@ -5,6 +5,10 @@ triggers:
 - github
 ---
 
+## Connection selection
+
+Use authenticated GitHub MCP tools first when they are available in the agent's environment. Detect this by tool availability, without depending on a particular MCP server name. Use the token and direct API instructions below only when GitHub MCP tools are unavailable or when raw API or `curl` access is explicitly needed.
+
 You have access to an environment variable, `GITHUB_TOKEN`, which allows you to interact with
 the GitHub API.
 
@@ -37,6 +41,29 @@ git remote -v && git branch # to find the current org, repo and branch
 git checkout -b create-widget && git add . && git commit -m "Create widget" && git push -u origin create-widget
 ```
 
+## Merging Pull Requests (async merge API)
+
+IMPORTANT:
+Only merge if the user asks you to, without ambiguity.
+
+GitHub released an async merge API in October 2026; it is now the
+recommended way to merge PRs programmatically, and the only merge API that supports stacked PRs. It can also add a PR to a merge queue.
+Prefer it over `PUT .../pulls/{n}/merge` and the GraphQL `mergePullRequest` mutation.
+A GitHub MCP merge tool may still use the older synchronous endpoint; for stacked PRs or merge queues, use the calls below.
+Docs: https://docs.github.com/en/rest/pulls/pulls#merge-a-pull-request-asynchronously
+
+1. Request the merge (`merge_action`: `default` uses the merge queue if the branch has one, else merges directly; or `direct_merge` / `merge_queue`). `merge_method`, `commit_title` and `commit_message` apply only to direct merges:
+```bash
+gh api -X PUT repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/merge-async -f merge_method=squash -f sha=<HEAD_SHA>
+```
+2. A `202` returns `details.uuid`; poll it every few seconds until `status` is no longer `pending`:
+```bash
+gh api repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/merge-async/<UUID>
+```
+
+Final `status` is `merged`, `enqueued` (added to the merge queue, NOT merged yet), or `failed` (see `details.message`).
+A `200` on the PUT means the PR is already merged or queued; a `409` means a merge request is already pending (its UUID is returned).
+
 ## Handling Review Comments
 
 - Critically evaluate each review comment before acting on it. Not all feedback is worth implementing: