@openhands/extensions 0.15.0 → 0.17.0

package/automations/catalog.schema.json

@@ -63,6 +63,10 @@
           "description": "direct only. What the automation is told to do. The rest of the create request restates the form, so it is not written here: the automation's name comes from this entry, the repository from the repo-picker field, and the trigger from the key and fields under form.triggers.",
           "$ref": "#/$defs/templateValue"
         },
+        "bundle": {
+          "description": "direct only, and the alternative to prompt. The script tarball this entry ships: the automation is deterministic machinery rather than judgement, so it runs as its own code and the host creates it through the raw create endpoint instead of a preset. The rest of the create request still restates the form, so it is not written here either.",
+          "$ref": "#/$defs/bundle"
+        },
         "filter": {
           "description": "direct only, and only for an event trigger. The expression deciding whether a delivered event belongs to this automation. It composes form values into a JMESPath expression, which is the one part of an event trigger that cannot be read off the form.",
           "$ref": "#/$defs/templateValue"
@@ -79,7 +83,10 @@
             "required": ["mode"]
           },
           "then": {
-            "required": ["prompt"]
+            "oneOf": [
+              { "required": ["prompt"], "not": { "required": ["bundle"] } },
+              { "required": ["bundle"], "not": { "required": ["prompt"] } }
+            ]
           }
         },
         {
@@ -91,6 +98,7 @@
             "required": ["message"],
             "allOf": [
               { "not": { "required": ["prompt"] } },
+              { "not": { "required": ["bundle"] } },
               { "not": { "required": ["filter"] } }
             ]
           }
@@ -108,6 +116,88 @@
             "required": ["form"]
           },
           "then": { "not": { "required": ["filter"] } }
+        },
+        {
+          "if": { "required": ["bundle"] },
+          "then": { "not": { "required": ["filter"] } }
+        }
+      ]
+    },
+    "bundle": {
+      "description": "What the host packs into a .tar.gz and uploads before creating the automation. It names files inside this repository and the command that runs them - never a host, a URL, or code to evaluate.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["version", "entrypoint", "files", "config"],
+      "properties": {
+        "version": {
+          "description": "The version of this bundle, recorded as the created automation's template provenance. Bump it when the shipped files or the config shape change: it is what tells an already-enabled deployment that what it installed is no longer current. Not the package version, which moves for reasons that have nothing to do with this entry.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 50,
+          "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
+        },
+        "entrypoint": {
+          "description": "The command the automation service runs inside the extracted tarball, such as `python3 main.py`. No shell metacharacters: the service rejects them, and a bundle has no reason to need one.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 500,
+          "pattern": "^[A-Za-z0-9 ._/-]+$"
+        },
+        "setupScript": {
+          "description": "Path inside the tarball to a script run once before the entrypoint, such as `setup.sh`. Absent when the bundle needs no installation step, which is the case for a standard-library script.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 255,
+          "pattern": "^[A-Za-z0-9._-]+(/[A-Za-z0-9._-]+)*$",
+          "not": { "pattern": "(^|/)\\.\\.?(/|$)" }
+        },
+        "timeout": {
+          "description": "Seconds a single run may take, when this entry needs more than the service default. A poll that fetches an archive per queued item needs longer than one that only calls an API.",
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 86400
+        },
+        "files": {
+          "description": "The tarball's contents, keyed by the path each file takes inside the archive and valued by where it lives in this repository. Stated rather than derived from the entry directory, so a script shipped by both a skill and the catalog has one copy rather than two.",
+          "type": "object",
+          "minProperties": 1,
+          "maxProperties": 32,
+          "propertyNames": {
+            "pattern": "^[A-Za-z0-9._-]+(/[A-Za-z0-9._-]+)*$",
+            "not": { "pattern": "(^|/)\\.\\.?(/|$)" },
+            "maxLength": 255
+          },
+          "additionalProperties": { "$ref": "#/$defs/bundleSource" }
+        },
+        "config": {
+          "description": "The config.json packed beside the entrypoint, rendered from the form. This is the bundle's analogue of prompt: the one thing that cannot be read off the form, because only the entry knows which key of its own script each field fills.",
+          "$ref": "#/$defs/bundleConfig"
+        }
+      }
+    },
+    "bundleSource": {
+      "description": "A file in this repository, as a repository-relative path under skills/ or automations/. No absolute path, no traversal, and no scheme, so a bundle cannot name anything outside the published package.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255,
+      "pattern": "^(skills|automations)/[A-Za-z0-9._-]+(/[A-Za-z0-9._-]+)*$",
+      "not": { "pattern": "(^|/)\\.\\.?(/|$)" }
+    },
+    "bundleConfig": {
+      "description": "The JSON document written to config.json. Its string leaves may embed the same placeholders every other value uses. It carries no markup rule, because it is written to a file rather than rendered.",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": { "$ref": "#/$defs/bundleConfigValue" }
+    },
+    "bundleConfigValue": {
+      "description": "A config leaf: a templated string, a number, a boolean, null, or an array or object of the same.",
+      "anyOf": [
+        { "$ref": "#/$defs/templateValue" },
+        { "type": ["number", "boolean", "null"] },
+        { "type": "array", "items": { "$ref": "#/$defs/bundleConfigValue" } },
+        {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/bundleConfigValue" }
         }
       ]
     },
@@ -224,6 +314,10 @@
         "default": { "type": "string" },
         "required": { "type": "boolean" },
         "provider": { "enum": ["github", "gitlab", "bitbucket"] },
+        "multiple": {
+          "description": "repo-picker only. The field collects several repositories rather than one, and its value is a list. A whole-value placeholder resolves to that list, so a payload can state `\"repos\": \"{{form.repositories}}\"` and get an array.",
+          "const": true
+        },
         "options": {
           "type": "array",
           "minItems": 1,
@@ -259,6 +353,13 @@
           },
           "then": { "required": ["provider"] }
         },
+        {
+          "if": {
+            "properties": { "type": { "not": { "const": "repo-picker" } } },
+            "required": ["type"]
+          },
+          "then": { "not": { "required": ["multiple"] } }
+        },
         {
           "if": {
             "properties": { "type": { "not": { "const": "select" } } },

package/automations/index.d.ts

@@ -63,6 +63,11 @@ export interface AutomationFormField {
   default?: string;
   required: boolean;
   provider?: AutomationGitProvider;
+  /**
+   * repo-picker only. The field collects several repositories rather than one,
+   * and its value is a list. A whole-value placeholder resolves to that list.
+   */
+  multiple?: true;
   options?: AutomationFieldOption[];
   constraints?: AutomationFieldConstraints;
 }
@@ -96,12 +101,40 @@ export interface AutomationForm {
   args: AutomationFormFields;
 }
 
+/** A config.json leaf: templated string, number, boolean, null, or a nesting of those. */
+export type AutomationBundleConfigValue =
+  | string
+  | number
+  | boolean
+  | null
+  | AutomationBundleConfigValue[]
+  | { [key: string]: AutomationBundleConfigValue };
+
+/**
+ * The script tarball a direct entry may ship instead of a prompt, for an
+ * automation that is deterministic machinery rather than judgement.
+ */
+export interface AutomationBundle {
+  /** The command run inside the extracted tarball. */
+  entrypoint: string;
+  /** Script run once before the entrypoint. Absent when nothing to install. */
+  setupScript?: string;
+  /** Seconds a run may take, when the service default is not enough. */
+  timeout?: number;
+  /** Packed path -> the repository path the file is read from at build time. */
+  files: Record<string, string>;
+  /** Rendered from the form and packed as config.json beside the entrypoint. */
+  config: Record<string, AutomationBundleConfigValue>;
+}
+
 export interface AutomationSetup {
   version: "1.0";
   mode: AutomationSetupMode;
   form: AutomationForm;
   /** direct only. What the automation is told to do. */
   prompt?: string;
+  /** direct only, and the alternative to `prompt`. Exactly one is present. */
+  bundle?: AutomationBundle;
   /** direct only, event trigger only. Which delivered events belong to it. */
   filter?: string;
   /**
@@ -130,17 +163,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 =
@@ -212,6 +370,10 @@ export interface AutomationInterfaceEndpoints {
   validate: string;
   createPrompt: string;
   createPlugin: string;
+  /** The raw create endpoint, which a bundle entry is created through. */
+  createBundle: string;
+  /** Where a bundle's tarball is uploaded before that create call. */
+  uploads: string;
 }
 
 export interface AutomationInterfaceManifest {
@@ -240,4 +402,15 @@ export function listAutomationCatalog(): RecommendedAutomation[];
 export function getAutomationCatalogEntry(
   id: string,
 ): RecommendedAutomation | undefined;
+/**
+ * Return the files a bundle entry ships, keyed by the path each takes inside
+ * the tarball, as an independent copy. Undefined for an entry with no bundle.
+ *
+ * The contents are inlined at build time from the repository paths
+ * `setup.bundle.files` names, because a host packing the tarball has the
+ * published package but not the repository.
+ */
+export function getAutomationBundleFiles(
+  id: string,
+): Record<string, string> | undefined;
 export default AUTOMATION_CATALOG;

package/automations/index.js

@@ -5,6 +5,7 @@
  * directory. `catalog-index.js` is generated from that directory so the JS
  * package can statically import each JSON file without an aggregate JSON asset.
  */
+import { AUTOMATION_BUNDLE_FILES } from "./bundle-index.js";
 import { AUTOMATION_CATALOG_ENTRIES } from "./catalog-index.js";
 import interfaceManifest from "./interface.json" with { type: "json" };
 
@@ -21,6 +22,19 @@ export const getAutomationCatalogEntry = (id) => {
 
 export const AUTOMATION_CATALOG = clone(AUTOMATIONS);
 
+/**
+ * The files a bundle entry ships, keyed by entry id and then by the path each
+ * file takes inside the tarball. Generated from the repository paths the
+ * entry's `setup.bundle.files` names, because a host packing the tarball has
+ * the package but not the repository.
+ *
+ * Absent for every entry that does not ship a bundle.
+ */
+export const getAutomationBundleFiles = (id) => {
+  const files = AUTOMATION_BUNDLE_FILES[id];
+  return files ? clone(files) : undefined;
+};
+
 /**
  * The production Automation interface manifest: the domain-level facts of the
  * interface, hand-authored in `automations/interface.json`.

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": {
@@ -59,7 +144,9 @@
     "capabilities": "/v1/capabilities",
     "validate": "/v1/validate",
     "createPrompt": "/v1/preset/prompt",
-    "createPlugin": "/v1/preset/plugin"
+    "createPlugin": "/v1/preset/plugin",
+    "createBundle": "/v1",
+    "uploads": "/v1/uploads"
   },
   "featuredAutomationIds": [
     "github-pr-reviewer",