@openhands/extensions 0.15.0 → 0.16.0

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.15.0"
+  ".": "0.16.0"
 }

package/automations/README.md

@@ -177,13 +177,26 @@ extension surface tomorrow) rather than between entries, so each is stated once
 Agent Canvas keeps its rendering components and reads every automation-specific datum from this file,
 falling back to its built-in defaults when the manifest is absent or fails admission:
 
-- **`routes`** - the list, setup, and detail routes. The host must have a registration serving each
-  declared shape, so admission verifies they match what it mounted; the manifest is the single source for
-  link construction.
-- **`navigation`** - the sidebar entry and the command-menu entry.
+- **`routes`** - the list, setup, detail, and templates routes. The host must have a registration serving
+  each declared shape, so admission verifies they match what it mounted; the manifest is the single source
+  for link construction.
+- **`navigation`** - the sidebar entry, the command-menu entry, and `subPages`: the ordered sub-page
+  navigation rendered inside the Automation interface, each item naming a `pages` entry with a label and
+  an icon slug from the host's closed icon map.
 - **`pages`** - page-identity copy: the list title and subtitle, the detail back label, the edit-dialog
-  title. Generic chrome - buttons, toasts, empty states, validation sentences - stays host copy, rendered
-  through the host's translations.
+  title, the templates title and description. Generic chrome - buttons, toasts, empty states, validation
+  sentences - stays host copy, rendered through the host's translations.
+- **`pages.list.overview` / `filters` / `sort` / `insights`** - the list page's dashboard composition.
+  Every value here names something the host implements from a closed set, and the manifest picks and
+  captions it: `overview.tiles[].metric` names a host-computed value (`automations`, `needs-attention`,
+  `total-runs`, `average-duration`), filter option values name host predicates (`status`: enabled /
+  latest-run-failed / disabled; `trigger`: `event` matches event-triggered automations, `schedule`
+  everything else), `sort` values name host comparators, and `insights` captions the host's run-health
+  states and per-automation stats. The health precedence, the run sampling, the value formatting, the
+  relative-time rendering, and the filtered-empty state with its reset button are the host's - a manifest
+  cannot redefine them, only relabel what appears. Tile `detail` copy is plain substitution over the
+  metric's placeholder namespace (only the `automations` metric exposes `{{active}}`); `zeroDetail`
+  replaces `detail` while the value is zero.
 - **`docsUrl`** - the automations documentation link, prefix-pinned to docs.openhands.dev by schema.
 - **`attributes`** - the input surface of an existing Automation: which attributes can be set after
   creation, keyed by the runtime-model property the host sends (`name`, `prompt`, `model`, `timeout`,
@@ -300,8 +313,8 @@ Recorded rather than resolved, because they need an owner outside this contract:
   related fields onto one line, which reads better; if that matters, it is a host concern, not an entry's.
 - **Assisted-setup completion.** The assisted flow ends at a conversation, so the host cannot emit a
   completion event. Until something reports back, the ratio of direct to assisted setup is not measurable.
-- **Delete confirmation and per-run views.** `interface.json` models the list, setup, and detail routes
-  and the settable attributes; deletion, run logs, and the dashboard sub-pages remain host-owned surfaces
-  with no manifest data of their own yet.
+- **Delete confirmation and per-run views.** `interface.json` models the routes, the settable attributes,
+  and the dashboard and templates sub-pages; deletion and run logs remain host-owned surfaces with no
+  manifest data of their own yet.
 - **Types from the schema.** `index.d.ts` is hand-written and mirrors `catalog.schema.json`. Generating it
   would remove that second source of truth.

package/automations/index.d.ts

@@ -130,17 +130,142 @@ export interface AutomationInterfaceRoutes {
   setup: string;
   /** Carries the `:automationId` segment the host substitutes. */
   detail: string;
+  /** The templates sub-page. Static: there is no parameter to substitute. */
+  templates: string;
+}
+
+/** An icon name from the host's closed icon map. */
+export type AutomationIconSlug =
+  | "layout-dashboard"
+  | "sparkles"
+  | "bot"
+  | "circle-alert"
+  | "activity"
+  | "timer";
+
+/** The pages a sub-page navigation item may point at. */
+export type AutomationSubPageId = "list" | "templates";
+
+export interface AutomationSubPageNavItem {
+  /** The `pages` entry this item navigates to; its route comes from `routes`. */
+  page: AutomationSubPageId;
+  label: string;
+  icon: AutomationIconSlug;
 }
 
 export interface AutomationInterfaceNavigation {
   sidebar: { label: string };
   commandMenu: { title: string; description: string; keywords: string };
+  /** The ordered sub-page navigation of the Automation interface. */
+  subPages: AutomationSubPageNavItem[];
+}
+
+/** A value the host computes; a tile picks and captions it, never defines it. */
+export type AutomationOverviewMetric =
+  | "automations"
+  | "needs-attention"
+  | "total-runs"
+  | "average-duration";
+
+/**
+ * One summary tile. `detail` captions the value; `zeroDetail`, when present,
+ * replaces it while the value is zero. Both are plain substitution over the
+ * metric's placeholder namespace: only the `automations` metric exposes
+ * `{{active}}`, so every other tile's copy is literal.
+ */
+export interface AutomationOverviewTile {
+  metric: AutomationOverviewMetric;
+  label: string;
+  detail: string;
+  zeroDetail?: string;
+  icon: AutomationIconSlug;
+}
+
+export interface AutomationOverview {
+  /** Names the tiles section for assistive technology. */
+  label: string;
+  tiles: AutomationOverviewTile[];
+}
+
+export type AutomationStatusFilterValue =
+  | "all"
+  | "active"
+  | "failing"
+  | "disabled";
+export type AutomationTriggerFilterValue = "all" | "schedule" | "event";
+
+/**
+ * A filter dropdown. Values name predicates the host implements; the manifest
+ * supplies which appear and their labels. `label` is the control's accessible
+ * name. The `all` option is the host's default and reset target.
+ */
+export interface AutomationStatusFilter {
+  id: "status";
+  label: string;
+  options: { value: AutomationStatusFilterValue; label: string }[];
+}
+
+export interface AutomationTriggerFilter {
+  id: "trigger";
+  label: string;
+  options: { value: AutomationTriggerFilterValue; label: string }[];
+}
+
+export type AutomationDashboardFilter =
+  | AutomationStatusFilter
+  | AutomationTriggerFilter;
+
+/** A comparator the host implements, named from a closed set. */
+export type AutomationSortValue = "last-run" | "runs" | "name";
+
+export interface AutomationDashboardSort {
+  /** The control's accessible name. */
+  label: string;
+  options: { value: AutomationSortValue; label: string }[];
+  /** Must be one of the declared option values. */
+  default: AutomationSortValue;
+}
+
+/**
+ * Copy for the per-automation run insights on cards and rows. The states,
+ * precedence, sampling, and value formatting are the host's; the manifest
+ * names them.
+ */
+export interface AutomationListInsights {
+  health: {
+    healthy: string;
+    failing: string;
+    running: string;
+    disabled: string;
+    neverRun: string;
+    checking: string;
+  };
+  lastRun: { label: string; never: string; justNow: string };
+  stats: { runs: string; recentSuccess: string; averageDuration: string };
+}
+
+/**
+ * The templates sub-page identity. Its body - the catalog cards and their
+ * launch behavior - is the host's existing catalog surface.
+ */
+export interface AutomationTemplatesPage {
+  title: string;
+  description: string;
 }
 
 export interface AutomationInterfacePages {
-  list: { title: string; subtitle: string };
+  list: {
+    title: string;
+    subtitle: string;
+    overview: AutomationOverview;
+    /** The filter dropdowns of the list page, in render order. */
+    filters: AutomationDashboardFilter[];
+    sort: AutomationDashboardSort;
+    insights: AutomationListInsights;
+  };
   detail: { backLabel: string };
   edit: { title: string };
+  templates: AutomationTemplatesPage;
 }
 
 export type AutomationAttributeType =

package/automations/interface.json

@@ -3,7 +3,8 @@
   "routes": {
     "list": "/automations",
     "setup": "/automations/new/:automationId",
-    "detail": "/automations/:automationId"
+    "detail": "/automations/:automationId",
+    "templates": "/automations/templates"
   },
   "navigation": {
     "sidebar": { "label": "Automate" },
@@ -11,15 +12,99 @@
       "title": "Automations",
       "description": "Review scheduled and webhook automations.",
       "keywords": "automate cron schedule webhook jobs"
-    }
+    },
+    "subPages": [
+      { "page": "list", "label": "Dashboard", "icon": "layout-dashboard" },
+      { "page": "templates", "label": "Templates", "icon": "sparkles" }
+    ]
   },
   "pages": {
     "list": {
-      "title": "Automations",
-      "subtitle": "View active and inactive automations, search by metadata, and inspect read-only details."
+      "title": "Dashboard",
+      "subtitle": "Health, activity, and run performance across your automations.",
+      "overview": {
+        "label": "Automation overview",
+        "tiles": [
+          {
+            "metric": "automations",
+            "label": "Automations",
+            "detail": "{{active}} active",
+            "icon": "bot"
+          },
+          {
+            "metric": "needs-attention",
+            "label": "Needs attention",
+            "detail": "Latest run failed",
+            "zeroDetail": "No latest-run failures",
+            "icon": "circle-alert"
+          },
+          {
+            "metric": "total-runs",
+            "label": "Total runs",
+            "detail": "Across loaded automations",
+            "icon": "activity"
+          },
+          {
+            "metric": "average-duration",
+            "label": "Average duration",
+            "detail": "Recent completed runs",
+            "icon": "timer"
+          }
+        ]
+      },
+      "filters": [
+        {
+          "id": "status",
+          "label": "Filter by status",
+          "options": [
+            { "value": "all", "label": "All statuses" },
+            { "value": "active", "label": "Active" },
+            { "value": "failing", "label": "Needs attention" },
+            { "value": "disabled", "label": "Disabled" }
+          ]
+        },
+        {
+          "id": "trigger",
+          "label": "Filter by trigger",
+          "options": [
+            { "value": "all", "label": "All triggers" },
+            { "value": "schedule", "label": "Scheduled" },
+            { "value": "event", "label": "Event-driven" }
+          ]
+        }
+      ],
+      "sort": {
+        "label": "Sort automations",
+        "default": "last-run",
+        "options": [
+          { "value": "last-run", "label": "Latest run" },
+          { "value": "runs", "label": "Most runs" },
+          { "value": "name", "label": "Name" }
+        ]
+      },
+      "insights": {
+        "health": {
+          "healthy": "Healthy",
+          "failing": "Failing",
+          "running": "Running",
+          "disabled": "Disabled",
+          "neverRun": "Never run",
+          "checking": "Checking"
+        },
+        "lastRun": { "label": "Last run", "never": "Never", "justNow": "Just now" },
+        "stats": {
+          "runs": "Runs",
+          "recentSuccess": "Recent success",
+          "averageDuration": "Avg. duration"
+        }
+      }
     },
     "detail": { "backLabel": "Back to Automations" },
-    "edit": { "title": "Edit automation" }
+    "edit": { "title": "Edit automation" },
+    "templates": {
+      "title": "Templates",
+      "description": "Browse proven automations and beta ideas, then launch one into a conversation to tailor it to your work."
+    }
   },
   "docsUrl": "https://docs.openhands.dev/openhands/usage/automations/overview",
   "attributes": {

package/automations/interface.schema.json

@@ -26,17 +26,21 @@
       "description": "The routes of the Automation interface. The host must have a registration serving each declared shape, so admission verifies they match what it mounted; the manifest is the single source for link construction.",
       "type": "object",
       "additionalProperties": false,
-      "required": ["list", "setup", "detail"],
+      "required": ["list", "setup", "detail", "templates"],
       "properties": {
         "list": { "$ref": "#/$defs/routePath" },
         "setup": { "$ref": "#/$defs/parameterizedRoutePath" },
-        "detail": { "$ref": "#/$defs/parameterizedRoutePath" }
+        "detail": { "$ref": "#/$defs/parameterizedRoutePath" },
+        "templates": {
+          "description": "The templates sub-page. Static: there is no parameter to substitute.",
+          "allOf": [{ "$ref": "#/$defs/routePath" }, { "not": { "pattern": ":" } }]
+        }
       }
     },
     "navigation": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["sidebar", "commandMenu"],
+      "required": ["sidebar", "commandMenu", "subPages"],
       "properties": {
         "sidebar": {
           "type": "object",
@@ -53,22 +57,46 @@
             "description": { "$ref": "#/$defs/copy" },
             "keywords": { "$ref": "#/$defs/copy" }
           }
+        },
+        "subPages": {
+          "description": "The ordered sub-page navigation of the Automation interface. Each page id may appear once; the host's admission checks that, since uniqueItems cannot see through differing labels.",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 2,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/subPageNavItem" }
         }
       }
     },
     "pages": {
-      "description": "Page-identity copy. Generic chrome - buttons, toasts, empty states, validation sentences - stays host copy, rendered through the host's translations.",
+      "description": "Page-identity copy, plus the list page's dashboard composition. Generic chrome - buttons, toasts, empty states, validation sentences - stays host copy, rendered through the host's translations.",
       "type": "object",
       "additionalProperties": false,
-      "required": ["list", "detail", "edit"],
+      "required": ["list", "detail", "edit", "templates"],
       "properties": {
         "list": {
           "type": "object",
           "additionalProperties": false,
-          "required": ["title", "subtitle"],
+          "required": ["title", "subtitle", "overview", "filters", "sort", "insights"],
           "properties": {
             "title": { "$ref": "#/$defs/copy" },
-            "subtitle": { "$ref": "#/$defs/copy" }
+            "subtitle": { "$ref": "#/$defs/copy" },
+            "overview": { "$ref": "#/$defs/overview" },
+            "filters": {
+              "description": "The filter dropdowns of the list page, in render order. Each filter id may appear once; the host's admission checks that.",
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 2,
+              "uniqueItems": true,
+              "items": {
+                "oneOf": [
+                  { "$ref": "#/$defs/statusFilter" },
+                  { "$ref": "#/$defs/triggerFilter" }
+                ]
+              }
+            },
+            "sort": { "$ref": "#/$defs/sort" },
+            "insights": { "$ref": "#/$defs/insights" }
           }
         },
         "detail": {
@@ -82,6 +110,16 @@
           "additionalProperties": false,
           "required": ["title"],
           "properties": { "title": { "$ref": "#/$defs/copy" } }
+        },
+        "templates": {
+          "description": "The templates sub-page identity. Its body - the catalog cards and their launch behavior - is the host's existing catalog surface.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["title", "description"],
+          "properties": {
+            "title": { "$ref": "#/$defs/copy" },
+            "description": { "$ref": "#/$defs/copy" }
+          }
         }
       }
     },
@@ -238,6 +276,228 @@
       "minItems": 1,
       "uniqueItems": true,
       "items": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" }
+    },
+    "iconSlug": {
+      "description": "An icon name from the host's closed icon map. The manifest picks from what the host ships; it cannot supply artwork.",
+      "enum": [
+        "layout-dashboard",
+        "sparkles",
+        "bot",
+        "circle-alert",
+        "activity",
+        "timer"
+      ]
+    },
+    "subPageNavItem": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["page", "label", "icon"],
+      "properties": {
+        "page": {
+          "description": "The pages entry this item navigates to; its route comes from routes.list or routes.templates.",
+          "enum": ["list", "templates"]
+        },
+        "label": { "$ref": "#/$defs/copy" },
+        "icon": { "$ref": "#/$defs/iconSlug" }
+      }
+    },
+    "overview": {
+      "description": "The summary tiles above the list. label names the section for assistive technology.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["label", "tiles"],
+      "properties": {
+        "label": { "$ref": "#/$defs/copy" },
+        "tiles": {
+          "description": "Each metric may appear once; the host's admission checks that.",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 8,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/overviewTile" }
+        }
+      }
+    },
+    "overviewTile": {
+      "description": "One summary tile. The metric names a value the host computes - a tile picks and captions it, never defines it. detail is the caption under the value; zeroDetail, when present, replaces it while the value is zero. Both are plain substitution over the metric's placeholder namespace: only the automations metric exposes {{active}}, so every other tile's copy is literal.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["metric", "label", "detail", "icon"],
+      "properties": {
+        "metric": {
+          "enum": ["automations", "needs-attention", "total-runs", "average-duration"]
+        },
+        "label": { "$ref": "#/$defs/copy" },
+        "detail": { "$ref": "#/$defs/copy" },
+        "zeroDetail": { "$ref": "#/$defs/copy" },
+        "icon": { "$ref": "#/$defs/iconSlug" }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "metric": { "const": "automations" } },
+            "required": ["metric"]
+          },
+          "then": {
+            "properties": {
+              "detail": { "not": { "pattern": "\\{\\{(?!active\\}\\})" } },
+              "zeroDetail": { "not": { "pattern": "\\{\\{(?!active\\}\\})" } }
+            }
+          },
+          "else": {
+            "properties": {
+              "detail": { "not": { "pattern": "\\{\\{" } },
+              "zeroDetail": { "not": { "pattern": "\\{\\{" } }
+            }
+          }
+        }
+      ]
+    },
+    "statusFilter": {
+      "description": "The status filter. Values name predicates the host implements over an automation and its derived health; the manifest supplies which appear and their labels. The all option is the host's default and reset target, so it must be offered.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "label", "options"],
+      "properties": {
+        "id": { "const": "status" },
+        "label": {
+          "description": "The control's accessible name.",
+          "$ref": "#/$defs/copy"
+        },
+        "options": {
+          "description": "Each value may appear once; the host's admission checks that.",
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 8,
+          "uniqueItems": true,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["value", "label"],
+            "properties": {
+              "value": { "enum": ["all", "active", "failing", "disabled"] },
+              "label": { "$ref": "#/$defs/copy" }
+            }
+          },
+          "contains": {
+            "type": "object",
+            "required": ["value"],
+            "properties": { "value": { "const": "all" } }
+          }
+        }
+      }
+    },
+    "triggerFilter": {
+      "description": "The trigger filter. Like the status filter, values name host-implemented predicates: event matches event-triggered automations, schedule everything else.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "label", "options"],
+      "properties": {
+        "id": { "const": "trigger" },
+        "label": {
+          "description": "The control's accessible name.",
+          "$ref": "#/$defs/copy"
+        },
+        "options": {
+          "description": "Each value may appear once; the host's admission checks that.",
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 8,
+          "uniqueItems": true,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["value", "label"],
+            "properties": {
+              "value": { "enum": ["all", "schedule", "event"] },
+              "label": { "$ref": "#/$defs/copy" }
+            }
+          },
+          "contains": {
+            "type": "object",
+            "required": ["value"],
+            "properties": { "value": { "const": "all" } }
+          }
+        }
+      }
+    },
+    "sort": {
+      "description": "The sort dropdown. Values name comparators the host implements. default must be one of the declared option values; the host's admission checks that, as schemas cannot cheaply.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["label", "options", "default"],
+      "properties": {
+        "label": {
+          "description": "The control's accessible name.",
+          "$ref": "#/$defs/copy"
+        },
+        "options": {
+          "description": "Each value may appear once; the host's admission checks that.",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 3,
+          "uniqueItems": true,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["value", "label"],
+            "properties": {
+              "value": { "$ref": "#/$defs/sortValue" },
+              "label": { "$ref": "#/$defs/copy" }
+            }
+          }
+        },
+        "default": { "$ref": "#/$defs/sortValue" }
+      }
+    },
+    "sortValue": { "enum": ["last-run", "runs", "name"] },
+    "insights": {
+      "description": "Copy for the per-automation run insights on cards and rows. The states, precedence, sampling, and value formatting are the host's; the manifest names them.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["health", "lastRun", "stats"],
+      "properties": {
+        "health": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "healthy",
+            "failing",
+            "running",
+            "disabled",
+            "neverRun",
+            "checking"
+          ],
+          "properties": {
+            "healthy": { "$ref": "#/$defs/copy" },
+            "failing": { "$ref": "#/$defs/copy" },
+            "running": { "$ref": "#/$defs/copy" },
+            "disabled": { "$ref": "#/$defs/copy" },
+            "neverRun": { "$ref": "#/$defs/copy" },
+            "checking": { "$ref": "#/$defs/copy" }
+          }
+        },
+        "lastRun": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["label", "never", "justNow"],
+          "properties": {
+            "label": { "$ref": "#/$defs/copy" },
+            "never": { "$ref": "#/$defs/copy" },
+            "justNow": { "$ref": "#/$defs/copy" }
+          }
+        },
+        "stats": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["runs", "recentSuccess", "averageDuration"],
+          "properties": {
+            "runs": { "$ref": "#/$defs/copy" },
+            "recentSuccess": { "$ref": "#/$defs/copy" },
+            "averageDuration": { "$ref": "#/$defs/copy" }
+          }
+        }
+      }
     }
   }
 }

package/package.json

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

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openhands-extensions"
-version = "0.15.0"
+version = "0.16.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.15.0"  # x-release-please-version
+_FALLBACK_VERSION = "0.16.0"  # x-release-please-version
 
 try:
     __version__: str = version("openhands-extensions")

package/tests/test_interface_manifest.py

@@ -76,6 +76,26 @@ def test_featured_automations_resolve_to_catalog_entries():
                 constraints={"max": 50}
             ),
         ),
+        (
+            "a sub-page the interface does not serve",
+            lambda doc: doc["navigation"]["subPages"][0].update(
+                page="workflows"
+            ),
+        ),
+        (
+            "an icon outside the host's icon map",
+            lambda doc: doc["navigation"]["subPages"][0].update(icon="rocket"),
+        ),
+        (
+            "tile copy using a placeholder its metric does not expose",
+            lambda doc: doc["pages"]["list"]["overview"]["tiles"][2].update(
+                detail="{{active}} runs"
+            ),
+        ),
+        (
+            "a status filter without the all option",
+            lambda doc: doc["pages"]["list"]["filters"][0]["options"].pop(0),
+        ),
     ],
 )
 def test_schema_rejects(case, mutation):