@openhands/extensions 0.10.0 → 0.12.0

package/automations/catalog/incident-retrospective-drafter/manifest.json

@@ -0,0 +1,100 @@
+{
+  "id": "incident-retrospective-drafter",
+  "name": "Incident retrospective drafter",
+  "category": "Reliability",
+  "description": "Collect incident chatter and issue updates, then draft a timeline and follow-up checklist.",
+  "requires": {
+    "integrations": {
+      "slack": {
+        "message": "Reads incident discussion and timestamps."
+      },
+      "linear": {
+        "message": "Reads follow-up tickets, owners, and status."
+      },
+      "notion": {
+        "message": "Publishes the drafted retrospective. Can be connected later during setup.",
+        "required": false
+      }
+    },
+    "features": [
+      "mcpTools",
+      "conversationDispatch"
+    ]
+  },
+  "popularityRank": 78,
+  "estimatedSetupMinutes": 8,
+  "skill": "incident-retrospective",
+  "exampleImplementation": "Trigger: manual, cron, or incident label added\nRequired MCPs: Slack, Linear, Notion\n\n1. Gather incident messages, timestamps, and linked issue references.\n2. Pull Linear follow-up tickets, owners, and status.\n3. TODO: define the incident identifier format and approved Notion template.\n4. Build a timeline, impact summary, root-cause hypotheses, and action items.\n5. Publish a draft retrospective and notify the incident owner.",
+  "setup": {
+    "version": "1.0",
+    "mode": "assisted",
+    "form": {
+      "note": "These answers start the conversation. Anything left blank is something the agent will ask about.",
+      "args": {
+        "incidentChannel": {
+          "type": "text",
+          "label": "Incident channel",
+          "help": "The Slack channel where incidents are discussed.",
+          "placeholder": "#incidents",
+          "required": false,
+          "constraints": {
+            "maxLength": 100
+          }
+        },
+        "linearTeam": {
+          "type": "text",
+          "label": "Linear team",
+          "help": "The team whose follow-up tickets belong in the retrospective.",
+          "required": false,
+          "constraints": {
+            "maxLength": 100
+          }
+        },
+        "notionDestination": {
+          "type": "text",
+          "label": "Notion destination",
+          "help": "Page or database where drafts should be published. Leave blank to decide during setup.",
+          "required": false,
+          "constraints": {
+            "maxLength": 200
+          }
+        },
+        "triggerPreference": {
+          "type": "select",
+          "label": "How should it run?",
+          "help": "A starting preference only. The agent confirms the exact trigger before creating anything.",
+          "default": "undecided",
+          "required": false,
+          "options": [
+            {
+              "value": "undecided",
+              "label": "Let the agent recommend one"
+            },
+            {
+              "value": "scheduled",
+              "label": "On a schedule"
+            },
+            {
+              "value": "onIncidentLabel",
+              "label": "When an incident is labelled"
+            },
+            {
+              "value": "manual",
+              "label": "Only when I run it"
+            }
+          ]
+        },
+        "notes": {
+          "type": "textarea",
+          "label": "Anything else the agent should know?",
+          "help": "Incident naming conventions, an existing retro template, who should be notified.",
+          "required": false,
+          "constraints": {
+            "maxLength": 2000
+          }
+        }
+      }
+    },
+    "message": "The user supplied these starting points. Confirm each one, ask about anything left blank, then create the automation.\n\n- Incident channel: {{form.incidentChannel}}\n- Linear team: {{form.linearTeam}}\n- Notion destination: {{form.notionDestination}}\n- Preferred trigger: {{form.triggerPreference}}\n- Notes: {{form.notes}}\n\nStill undecided and required before creation: the incident identifier format and the approved Notion retrospective template."
+  }
+}

package/automations/catalog/{jira-issue-to-pr.json → jira-issue-to-pr/manifest.json}

@@ -3,12 +3,17 @@
   "name": "Jira issue to GitHub PR",
   "category": "Project management",
   "description": "Watch a Jira Cloud project for issues with a configurable label and automatically open a GitHub pull request for each new issue found. The target GitHub repo is read from the ticket body - no repo parameter required at deploy time.",
-  "requiredIntegrationIds": [
-    "jira",
-    "github"
-  ],
+  "requires": {
+    "integrations": {
+      "jira": {
+        "message": "Reads the project for issues carrying the trigger label."
+      },
+      "github": {
+        "message": "Opens a pull request on the repository named in the ticket."
+      }
+    }
+  },
   "popularityRank": 85,
   "estimatedSetupMinutes": 5,
-  "prompt": "Set up a Jira automation to create pull requests",
   "exampleImplementation": "Trigger: cron polling (e.g. every 5 minutes)\nRequired secrets: Jira API token, GitHub personal access token (repo + workflow scope)\n\n1. Collect Jira base URL, email, API token secret name, label to watch, and cron schedule from the user. No GitHub repo is needed at deploy time - each ticket must include the target repo (owner/repo) in its body.\n2. Poll POST /rest/api/3/search/jql on the Jira Cloud instance to find open issues carrying the configured label.\n3. Deduplicate against a KV-store-backed set of already-processed issue keys so re-runs never create duplicate PRs.\n4. For each new issue, start an independent OpenHands agent conversation that extracts the GitHub repo from the ticket body, clones it, creates a branch named after the Jira key, implements or scaffolds the requested change, and opens a pull request.\n5. Immediately after the conversation is created, post a Jira comment on the issue: 'I'm on it: <conversation URL>'.\n6. Persist the processed issue key immediately after dispatching so the next poll skips it."
 }

package/automations/catalog/{linear-triage-assistant.json → linear-triage-assistant/manifest.json}

@@ -3,11 +3,15 @@
   "name": "Linear issue triage assistant",
   "category": "Project management",
   "description": "Classify new Linear issues, suggest labels, find duplicates, and ask clarifying questions.",
-  "requiredIntegrationIds": [
-    "linear"
-  ],
+  "requires": {
+    "integrations": {
+      "linear": {
+        "message": "Reads new issues and applies labels, comments, and duplicate links."
+      }
+    }
+  },
   "popularityRank": 90,
   "estimatedSetupMinutes": 3,
-  "prompt": "/linear-triage:setup",
+  "skill": "linear-triage",
   "exampleImplementation": "Trigger: linear Issue create\nRequired MCP: Linear\n\n1. Load the new issue, team context, project, labels, and recent similar issues.\n2. Score priority and classify the request as bug, feature, support, or chore.\n3. TODO: map local team labels and priority conventions.\n4. Add a triage comment with rationale and suggested next actions.\n5. Optionally update labels, priority, and assignee."
 }

package/automations/catalog/{research-brief-writer.json → research-brief-writer/manifest.json}

@@ -3,12 +3,18 @@
   "name": "Research brief writer",
   "category": "Research",
   "description": "Monitor a topic, gather sources from the web, and publish a short brief for your team.",
-  "requiredIntegrationIds": [
-    "tavily",
-    "notion"
-  ],
+  "requires": {
+    "integrations": {
+      "tavily": {
+        "message": "Searches the web for sources on the topic."
+      },
+      "notion": {
+        "message": "Publishes the finished brief."
+      }
+    }
+  },
   "popularityRank": 84,
   "estimatedSetupMinutes": 7,
-  "prompt": "/research-brief:setup",
+  "skill": "research-brief",
   "exampleImplementation": "Trigger: cron, weekly or daily\nRequired MCPs: Tavily, Notion\n\n1. Run focused Tavily searches for configured topics and competitors.\n2. Deduplicate sources and rank them by freshness and authority.\n3. TODO: confirm citation format and destination Notion database schema.\n4. Write an executive summary, implications, and recommended actions.\n5. Create or update a Notion page with citations and source links."
 }

package/automations/catalog/{slack-channel-monitor.json → slack-channel-monitor/manifest.json}

@@ -3,9 +3,14 @@
   "name": "Slack channel monitor",
   "category": "Team communication",
   "description": "Watch Slack channels for @openhands mentions, open a conversation with the message context, reply when the agent finishes, and continue the same conversation from triggered Slack thread follow-ups.",
-  "requiredIntegrationIds": ["slack"],
+  "requires": {
+    "integrations": {
+      "slack": {
+        "message": "Reads channel messages and posts replies back to the thread."
+      }
+    }
+  },
   "popularityRank": 92,
   "estimatedSetupMinutes": 7,
-  "prompt": "/slack-monitor:poll",
   "exampleImplementation": "Trigger: cron, every minute\nRequired secret: SLACK_BOT_TOKEN or SLACK_USER_TOKEN\n\n1. Poll up to 10 configured Slack channels for new messages since the last run.\n2. Match messages containing the trigger phrase (default: @openhands).\n3. React with 👀 and start an OpenHands conversation with the message and recent channel context.\n4. Post a thread reply with a link to the conversation, then post the agent response when done.\n5. Keep the thread in a short follow-up watch window and forward only replies that repeat the trigger phrase to the same conversation, with per-thread backoff for quiet threads."
 }

package/automations/catalog/{slack-standup-digest.json → slack-standup-digest/manifest.json}

@@ -2,12 +2,15 @@
   "id": "slack-standup-digest",
   "name": "Slack standup digest",
   "category": "Team updates",
-  "description": "Summarize yesterday\u2019s Slack activity into an async standup note with blockers, decisions, and owners.",
-  "requiredIntegrationIds": [
-    "slack"
-  ],
+  "description": "Summarize yesterday’s Slack activity into an async standup note with blockers, decisions, and owners.",
+  "requires": {
+    "integrations": {
+      "slack": {
+        "message": "Reads recent channel activity and posts the digest."
+      }
+    }
+  },
   "popularityRank": 94,
   "estimatedSetupMinutes": 5,
-  "prompt": "/standup-digest:setup",
   "exampleImplementation": "Trigger: cron, weekday mornings\nRequired MCP: Slack\n\n1. Search configured channels for messages since the last digest window.\n2. Cluster updates into shipped work, active work, blockers, and decisions.\n3. TODO: choose a safe allowlist for channels and whether DMs are excluded.\n4. Draft a Slack message with owners, links, and unanswered questions.\n5. Optionally post to the configured standup channel."
 }

package/automations/catalog-index.js

@@ -0,0 +1,23 @@
+// This file is auto-generated by scripts/build-automation-catalog.mjs.
+// Do not edit it manually. To update it after changing automations/catalog/*/manifest.json,
+// run: npm run build:automations
+
+import entry0 from "./catalog/github-pr-reviewer/manifest.json" with { type: "json" };
+import entry1 from "./catalog/github-repo-monitor/manifest.json" with { type: "json" };
+import entry2 from "./catalog/slack-standup-digest/manifest.json" with { type: "json" };
+import entry3 from "./catalog/slack-channel-monitor/manifest.json" with { type: "json" };
+import entry4 from "./catalog/linear-triage-assistant/manifest.json" with { type: "json" };
+import entry5 from "./catalog/jira-issue-to-pr/manifest.json" with { type: "json" };
+import entry6 from "./catalog/research-brief-writer/manifest.json" with { type: "json" };
+import entry7 from "./catalog/incident-retrospective-drafter/manifest.json" with { type: "json" };
+
+export const AUTOMATION_CATALOG_ENTRIES = [
+  entry0,
+  entry1,
+  entry2,
+  entry3,
+  entry4,
+  entry5,
+  entry6,
+  entry7,
+];

package/automations/catalog.schema.json

@@ -0,0 +1,273 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/OpenHands/extensions/automations/catalog.schema.json",
+  "title": "AutomationCatalogEntry",
+  "description": "Strict schema for automations/catalog/<id>/manifest.json. Mirrors automations/index.d.ts. An entry carries the card metadata Agent Canvas renders plus, optionally, the extension-owned setup contract for that automation. It states only what varies between automations, and states each of those things once: anything the host can derive from another field is absent by design.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "name",
+    "category",
+    "description",
+    "requires",
+    "popularityRank",
+    "estimatedSetupMinutes",
+    "exampleImplementation"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+      "description": "Stable identifier. Must equal the name of the directory holding this manifest."
+    },
+    "name": { "type": "string", "minLength": 1 },
+    "category": { "type": "string", "minLength": 1 },
+    "description": { "type": "string", "minLength": 1 },
+    "requires": { "$ref": "#/$defs/requires" },
+    "popularityRank": { "type": "integer", "minimum": 0 },
+    "estimatedSetupMinutes": { "type": "integer", "minimum": 1 },
+    "skill": {
+      "description": "The skills/ directory that builds this automation today. Defaults to `id`, so it is stated only where the two differ. How that skill is invoked is not repeated here: the command lives once, in the skill's own `triggers:` frontmatter, and the skills catalog exposes it.",
+      "type": "string",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+    },
+    "exampleImplementation": {
+      "description": "What the skill builds. Documentation for authors; Agent Canvas does not render it.",
+      "type": "string",
+      "minLength": 1
+    },
+    "setup": { "$ref": "#/$defs/setup" }
+  },
+  "$defs": {
+    "setup": {
+      "description": "The extension-owned configuration experience for this automation: what the deployment must support, what must be connected first, what the user is asked, how a draft is validated, what request is sent, and which analytics stages are emitted. It never describes what the automation does at runtime - that is the preset, owned by OpenHands/automation. It is data, not code - there is no key that accepts JavaScript, no markup in copy, no free-form URL, and no secret value.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "version",
+        "mode",
+        "form"
+      ],
+      "properties": {
+        "version": {
+          "const": "1.0",
+          "description": "Selects how this block is interpreted. A future format ships a new constant."
+        },
+        "mode": {
+          "enum": ["direct", "assisted"],
+          "description": "direct - the form produces a request body. assisted - the form seeds an agent conversation that finishes setup."
+        },
+        "form": { "$ref": "#/$defs/form" },
+        "prompt": {
+          "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"
+        },
+        "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"
+        },
+        "message": {
+          "description": "assisted only. Setup context handed to the agent conversation that finishes setup. The command that opens it comes from the skill, so it is not repeated here. Capped so this never becomes a channel for runtime instructions.",
+          "allOf": [{ "$ref": "#/$defs/templateCopy" }, { "maxLength": 2000 }]
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "mode": { "const": "direct" } },
+            "required": ["mode"]
+          },
+          "then": {
+            "required": ["prompt"],
+            "not": { "required": ["message"] }
+          }
+        },
+        {
+          "if": {
+            "properties": { "mode": { "const": "assisted" } },
+            "required": ["mode"]
+          },
+          "then": {
+            "required": ["message"],
+            "allOf": [
+              { "not": { "required": ["prompt"] } },
+              { "not": { "required": ["filter"] } }
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "form": {
+                "properties": {
+                  "triggers": { "not": { "required": ["event"] } }
+                },
+                "required": ["triggers"]
+              }
+            },
+            "required": ["form"]
+          },
+          "then": { "not": { "required": ["filter"] } }
+        }
+      ]
+    },
+    "copy": {
+      "description": "Literal user-visible copy. Carries no markup, because a setup block must never inject HTML into the host.",
+      "type": "string",
+      "minLength": 1,
+      "not": { "pattern": "<[A-Za-z/!]" }
+    },
+    "placeholders": {
+      "$comment": "Every {{ must open a known placeholder namespace and close immediately. `form` resolves against the values the user entered; `automation` against the catalog entry this setup block belongs to. There is deliberately no secrets namespace.",
+      "not": {
+        "pattern": "\\{\\{(?!(form|automation)\\.[A-Za-z0-9_.]+\\}\\})"
+      }
+    },
+    "templateCopy": {
+      "description": "User-visible copy that may embed {{namespace.key}} placeholders.",
+      "allOf": [
+        { "$ref": "#/$defs/copy" },
+        { "$ref": "#/$defs/placeholders" }
+      ]
+    },
+    "templateValue": {
+      "description": "A request-body string that may embed placeholders. Not rendered, so expression syntax such as a JMESPath filter is allowed.",
+      "type": "string",
+      "minLength": 1,
+      "allOf": [{ "$ref": "#/$defs/placeholders" }]
+    },
+    "requires": {
+      "description": "What must be connected, and what the deployment must offer, for this automation to be usable. Every entry carries it, whether or not it ships a setup block, so the integrations an automation needs are recorded in exactly one place. The host decides what to do when a requirement is unmet; an entry only states the requirement and why it exists.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["integrations"],
+      "properties": {
+        "integrations": {
+          "description": "Keyed by integration id, each of which must resolve to an integrations/catalog entry.",
+          "type": "object",
+          "minProperties": 1,
+          "propertyNames": { "type": "string", "minLength": 1 },
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["message"],
+            "properties": {
+              "message": {
+                "description": "Why this automation needs the integration. Required, so an integration is never listed without saying what it is for.",
+                "$ref": "#/$defs/copy"
+              },
+              "required": {
+                "description": "Defaults to true. Set false to let setup continue while the integration is still unconnected.",
+                "const": false
+              }
+            }
+          }
+        },
+        "features": {
+          "description": "Deployment capabilities this automation cannot run without. Names are matched against the capabilities endpoint the host queries.",
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "form": {
+      "description": "The inputs the user is asked for. These constraints are also what the host validates locally, so no separate validation block restates them.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["args"],
+      "properties": {
+        "note": { "$ref": "#/$defs/copy" },
+        "triggers": {
+          "description": "Inputs that decide when the automation runs, keyed by trigger kind. The key set is the trigger kinds the deployment must support, so it is not restated anywhere else.",
+          "type": "object",
+          "additionalProperties": false,
+          "minProperties": 1,
+          "properties": {
+            "cron": { "$ref": "#/$defs/formFields" },
+            "event": { "$ref": "#/$defs/formFields" }
+          }
+        },
+        "args": {
+          "description": "Every other input: the arguments to the automation itself.",
+          "$ref": "#/$defs/formFields"
+        }
+      }
+    },
+    "formFields": {
+      "description": "Keyed by field name, which is what {{form.<name>}} resolves against.",
+      "type": "object",
+      "minProperties": 1,
+      "propertyNames": { "pattern": "^[a-z][A-Za-z0-9]*$" },
+      "additionalProperties": { "$ref": "#/$defs/formField" }
+    },
+    "formField": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "label", "help", "required"],
+      "properties": {
+        "type": {
+          "description": "Semantic field types. The host renders a cron field without knowing what cron means to an automation, and resolves the deployment's schedule limits and timezone list for the cron and timezone types, so an entry never restates them.",
+          "enum": [
+            "text",
+            "textarea",
+            "select",
+            "cron",
+            "timezone",
+            "repo-picker"
+          ]
+        },
+        "label": { "$ref": "#/$defs/copy" },
+        "help": { "$ref": "#/$defs/copy" },
+        "placeholder": { "$ref": "#/$defs/copy" },
+        "default": { "type": "string" },
+        "required": { "type": "boolean" },
+        "provider": { "enum": ["github", "gitlab", "bitbucket"] },
+        "options": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["value", "label"],
+            "properties": {
+              "value": { "type": "string", "minLength": 1 },
+              "label": { "$ref": "#/$defs/copy" }
+            }
+          }
+        },
+        "constraints": {
+          "type": "object",
+          "additionalProperties": false,
+          "minProperties": 1,
+          "properties": {
+            "minLength": { "type": "integer", "minimum": 0 },
+            "maxLength": { "type": "integer", "minimum": 1 },
+            "format": {
+              "description": "A host-implemented check, named from a closed set. Setup blocks cannot supply their own regex, so one cannot hand the host a pathological pattern. safeExpressionLiteral marks a value that is interpolated into a filter expression string literal, so quotes and backslashes must be rejected before they can break the expression.",
+              "enum": ["safeExpressionLiteral"]
+            }
+          }
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "type": { "const": "repo-picker" } },
+            "required": ["type"]
+          },
+          "then": { "required": ["provider"] }
+        },
+        {
+          "if": {
+            "properties": { "type": { "not": { "const": "select" } } },
+            "required": ["type"]
+          },
+          "then": { "not": { "required": ["options"] } }
+        }
+      ]
+    }
+  }
+}

package/automations/index.d.ts

@@ -3,12 +3,120 @@ export interface RecommendedAutomation {
   name: string;
   category: string;
   description: string;
-  prompt: string;
-  exampleImplementation: string;
-  requiredIntegrationIds: string[];
+  requires: AutomationPrerequisites;
   popularityRank: number;
   estimatedSetupMinutes: number;
+  /**
+   * The `skills/` directory that builds this automation today. Defaults to
+   * `id`; present only where the two differ. Look the launch command up from
+   * that skill's entry in `SKILLS_CATALOG` rather than storing it here.
+   */
+  skill?: string;
+  exampleImplementation: string;
+  /** Present when this automation ships an extension-owned setup experience. */
+  setup?: AutomationSetup;
+}
+
+/**
+ * The extension-owned configuration experience for one automation.
+ *
+ * Mirrors the `setup` block in `automations/catalog.schema.json`, which is
+ * authoritative. It describes how an automation is *configured*; it never
+ * describes what the automation does at runtime.
+ *
+ * It states only what varies between automations, and states each of those
+ * things once. Everything else is the same for every automation and is the
+ * host's to generate: the slash command (`/<id>:setup`), the setup route
+ * (`/automations/new/<id>`), the capabilities check, the preflight call, the
+ * mapping from a rejected payload path back to the input at fault, the review
+ * screen, the navigation after a success, and the analytics stages.
+ */
+
+export type AutomationSetupMode = "direct" | "assisted";
+export type AutomationFieldType =
+  | "text"
+  | "textarea"
+  | "select"
+  | "cron"
+  | "timezone"
+  | "repo-picker";
+export type AutomationGitProvider = "github" | "gitlab" | "bitbucket";
+export type AutomationTriggerKind = "cron" | "event";
+
+export interface AutomationFieldOption {
+  value: string;
+  label: string;
+}
+
+export interface AutomationFieldConstraints {
+  minLength?: number;
+  maxLength?: number;
+  /** Host-implemented check, named from a closed set. Entries supply no regex. */
+  format?: "safeExpressionLiteral";
+}
+
+export interface AutomationFormField {
+  type: AutomationFieldType;
+  label: string;
+  help: string;
+  placeholder?: string;
+  default?: string;
+  required: boolean;
+  provider?: AutomationGitProvider;
+  options?: AutomationFieldOption[];
+  constraints?: AutomationFieldConstraints;
+}
+
+/** Keyed by field name, which is what `{{form.<name>}}` resolves against. */
+export type AutomationFormFields = Record<string, AutomationFormField>;
+
+export interface AutomationIntegrationRequirement {
+  /** Why this automation needs it. Omitted when there is no setup flow to show it in. */
+  message?: string;
+  /** Defaults to true. `false` lets setup continue while it is unconnected. */
+  required?: false;
+}
+
+export interface AutomationPrerequisites {
+  /** Keyed by integration catalog id. */
+  integrations: Record<string, AutomationIntegrationRequirement>;
+  /** Deployment capabilities this automation cannot run without. */
+  features?: string[];
+}
+
+/** The inputs that decide when the automation runs, keyed by trigger kind. */
+export type AutomationTriggerForm = Partial<
+  Record<AutomationTriggerKind, AutomationFormFields>
+>;
+
+export interface AutomationForm {
+  note?: string;
+  triggers?: AutomationTriggerForm;
+  /** Every other input: the arguments to the automation itself. */
+  args: AutomationFormFields;
+}
+
+export interface AutomationSetup {
+  version: "1.0";
+  mode: AutomationSetupMode;
+  form: AutomationForm;
+  /** direct only. What the automation is told to do. */
+  prompt?: string;
+  /** direct only, event trigger only. Which delivered events belong to it. */
+  filter?: string;
+  /** assisted only. Setup context for the conversation that finishes setup. */
+  message?: string;
 }
 
 export const AUTOMATION_CATALOG: RecommendedAutomation[];
+/**
+ * Return the full automation catalog.
+ * Reads the generated static import index over `automations/catalog/<id>/manifest.json`.
+ * Returns an independent copy.
+ */
+export function listAutomationCatalog(): RecommendedAutomation[];
+/** Return one automation catalog entry by id as an independent copy. */
+export function getAutomationCatalogEntry(
+  id: string,
+): RecommendedAutomation | undefined;
 export default AUTOMATION_CATALOG;