🙌 OpenHands: AI-Driven Development
feat: add a domain-neutral extension-manifest host (#16127)
Hiep Le8e5dc4300465
diff --git a/__tests__/components/automations/recommended-automations.test.tsx b/__tests__/components/automations/recommended-automations.test.tsxindex 89acc81350..10ca335ffc 100644--- a/__tests__/components/automations/recommended-automations.test.tsx+++ b/__tests__/components/automations/recommended-automations.test.tsx@@ -17,11 +17,12 @@ import {setRegisteredBackends,} from "#/api/backend-registry/active-store";import { ActiveBackendProvider } from "#/contexts/active-backend-context";-import type { Backend } from "#/api/backend-registry/types";import {- RecommendedAutomationsLauncher,- buildAutomationPrompt,-} from "#/components/features/automations/recommended-automations-launcher";+ NavigationProvider,+ type NavigationContextValue,+} from "#/context/navigation-context";+import type { Backend } from "#/api/backend-registry/types";+import { RecommendedAutomationsLauncher } from "#/components/features/automations/recommended-automations-launcher";import {RecommendedAutomationsSection,getAutomationsByPopularity,@@ -75,12 +76,25 @@ const cloudBackend: Backend = {kind: "cloud",};+const mockNavigate = vi.fn();++const navigationValue: NavigationContextValue = {+ currentPath: "/automations",+ conversationId: null,+ isNavigating: false,+ navigate: mockNavigate,+};+function renderLauncher({ withBackendProvider = false } = {}) {const queryClient = new QueryClient({defaultOptions: { queries: { retry: false }, mutations: { retry: false } },});- const launcher = <RecommendedAutomationsLauncher />;+ const launcher = (+ <NavigationProvider value={navigationValue}>+ <RecommendedAutomationsLauncher />+ </NavigationProvider>+ );return render(<QueryClientProvider client={queryClient}>@@ -383,26 +397,73 @@ describe("recommended automations", () => {expect(mockCreateConversationMutate).not.toHaveBeenCalled();});- it("launches directly with the catalog prompt when the required MCP is already installed", () => {+ it("opens the setup form for an automation that ships one, creating nothing", () => {+ // ArrangemockUseSettings.mockReturnValue({data: settingsWithGithubMcp(),});renderLauncher();+ // ActfireEvent.click(screen.getByTestId("recommended-automation-card-github-pr-reviewer"),);fireEvent.click(screen.getByTestId("responder-deployment-continue-local"));- expect(mockCreateConversationMutate).toHaveBeenCalledTimes(1);- expect(screen.queryByTestId("mcp-install-modal")).not.toBeInTheDocument();+ // Assert — nothing exists until the user confirms in the setup form.+ expect(mockNavigate).toHaveBeenCalledWith(+ "/automations/new/github-pr-reviewer",+ );+ expect(mockCreateConversationMutate).not.toHaveBeenCalled();+ });+ it("launches an automation that ships no setup form with its slash command", () => {+ // Arrange+ mockUseSettings.mockReturnValue({+ data: settingsWithMcpConfig({+ linear: { url: "https://mcp.linear.app/mcp" },+ }),+ });++ renderLauncher();++ // Act+ fireEvent.click(+ screen.getByTestId("recommended-automation-card-linear-triage-assistant"),+ );++ // Assert+ expect(mockCreateConversationMutate).toHaveBeenCalledTimes(1);const [, options] = mockCreateConversationMutate.mock.calls[0];options.onSuccess({ conversation_id: "conversation-1" });const draft = getConversationState("conversation-1").draftMessage;- expect(draft).toBeTruthy();+ expect(draft).toBe("/linear-triage:setup");+ });++ it("launches without waiting for an integration the automation can start without", () => {+ // Arrange — Slack and Linear are connected; Notion, which the entry marks+ // as connectable later, is not.+ mockUseSettings.mockReturnValue({+ data: settingsWithMcpConfig({+ slack: { url: "https://mcp.slack.com/mcp" },+ linear: { url: "https://mcp.linear.app/mcp" },+ }),+ });++ renderLauncher();++ // Act+ fireEvent.click(+ screen.getByTestId(+ "recommended-automation-card-incident-retrospective-drafter",+ ),+ );++ // Assert — nothing stands between the click and the launch.+ expect(screen.queryByTestId("mcp-install-modal")).not.toBeInTheDocument();+ expect(mockNavigate).toHaveBeenCalledTimes(1);});it("prompts to install when the required MCP server is disabled", async () => {@@ -445,7 +506,7 @@ describe("recommended automations", () => {screen.getByTestId("recommended-automation-card-github-pr-reviewer"),);- expect(mockCreateConversationMutate).toHaveBeenCalledTimes(1);+ expect(mockNavigate).toHaveBeenCalledTimes(1);});it("hides the recommended automations section on cloud backends", () => {@@ -479,7 +540,9 @@ describe("recommended automations", () => {await waitFor(() => expect(saveSpy).toHaveBeenCalledTimes(1));await waitFor(() =>- expect(mockCreateConversationMutate).toHaveBeenCalledTimes(1),+ expect(mockNavigate).toHaveBeenCalledWith(+ "/automations/new/github-pr-reviewer",+ ),);});@@ -517,14 +580,3 @@ describe("recommended automations", () => {).not.toBeInTheDocument();});});--describe("buildAutomationPrompt", () => {- it("passes the prompt through verbatim", () => {- expect(buildAutomationPrompt("Do something useful")).toBe(- "Do something useful",- );- expect(buildAutomationPrompt("/slack-monitor:poll")).toBe(- "/slack-monitor:poll",- );- });-});diff --git a/__tests__/components/manifest/manifest-form-field.test.tsx b/__tests__/components/manifest/manifest-form-field.test.tsxnew file mode 100644index 0000000000..0760a7c06a--- /dev/null+++ b/__tests__/components/manifest/manifest-form-field.test.tsx@@ -0,0 +1,119 @@+import { useState } from "react";+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";+import { render, screen } from "@testing-library/react";+import userEvent from "@testing-library/user-event";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import {+ __resetActiveStoreForTests,+ setActiveSelection,+ setRegisteredBackends,+} from "#/api/backend-registry/active-store";+import { SetupFormField } from "#/components/features/manifest/manifest-form-field";+import { ActiveBackendProvider } from "#/contexts/active-backend-context";+import type { Backend } from "#/api/backend-registry/types";+import type { SetupFormField as SetupFormFieldDefinition } from "#/manifests/types";++const LOCAL_BACKEND: Backend = {+ id: "local-1",+ name: "Local",+ host: "http://localhost:18000",+ apiKey: "",+ kind: "local",+};++const CLOUD_BACKEND: Backend = {+ id: "cloud-1",+ name: "OpenHands Cloud",+ host: "https://app.all-hands.dev",+ apiKey: "bearer-token",+ kind: "cloud",+};++/** The repository input `github-pr-reviewer` declares, in its published shape. */+const REPOSITORY_FIELD: SetupFormFieldDefinition = {+ type: "repo-picker",+ label: "Repository",+ help: "The repository whose pull requests will be reviewed.",+ provider: "github",+ required: true,+};++/** Holds the field value the way the setup dialog does, so typing accumulates. */+function Harness({ onValueChange }: { onValueChange: (value: string) => void }) {+ const [value, setValue] = useState("");++ return (+ <SetupFormField+ name="repository"+ field={REPOSITORY_FIELD}+ value={value}+ options={[]}+ repository={null}+ disabled={false}+ onChange={(next) => {+ setValue(next);+ onValueChange(next);+ }}+ onRepositoryChange={vi.fn()}+ onBlur={vi.fn()}+ />+ );+}++function renderRepositoryField(backend: Backend) {+ setRegisteredBackends([backend]);+ setActiveSelection({ backendId: backend.id });++ const onValueChange = vi.fn();+ render(+ <QueryClientProvider+ client={+ new QueryClient({ defaultOptions: { queries: { retry: false } } })+ }+ >+ <ActiveBackendProvider>+ <Harness onValueChange={onValueChange} />+ </ActiveBackendProvider>+ </QueryClientProvider>,+ );++ return { onValueChange, user: userEvent.setup() };+}++beforeEach(() => {+ __resetActiveStoreForTests();+});++afterEach(() => {+ __resetActiveStoreForTests();+});++describe("SetupFormField repo-picker", () => {+ it("lets a repository be typed on a backend that cannot list them", async () => {+ // Arrange — a local backend, where GitService answers every repository+ // query with an empty page.+ const { onValueChange, user } = renderRepositoryField(LOCAL_BACKEND);++ // Act+ await user.type(+ screen.getByTestId("setup-field-repository"),+ "OpenHands/agent-server-gui",+ );++ // Assert — the required field is answerable, in the `owner/repo` shape the+ // create payload sends as `repos[0].url`.+ expect(onValueChange).toHaveBeenLastCalledWith(+ "OpenHands/agent-server-gui",+ );+ });++ it("browses the account's repositories on a cloud backend", () => {+ // Arrange / Act+ renderRepositoryField(CLOUD_BACKEND);++ // Assert — the picker stays the way a repository is chosen wherever it can+ // actually answer, so there is nothing to type into.+ expect(screen.getByTestId("git-repo-dropdown")).toBeInTheDocument();+ expect(screen.queryByTestId("setup-field-repository")).toBeNull();+ });+});diff --git a/__tests__/components/manifest/manifest-setup-dialog.test.tsx b/__tests__/components/manifest/manifest-setup-dialog.test.tsxnew file mode 100644index 0000000000..1ddb423454--- /dev/null+++ b/__tests__/components/manifest/manifest-setup-dialog.test.tsx@@ -0,0 +1,214 @@+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";+import { render, screen, waitFor } from "@testing-library/react";+import userEvent from "@testing-library/user-event";+import { beforeEach, describe, expect, it, vi } from "vitest";+import AutomationService from "#/api/automation-service/automation-service.api";+import { SetupDialog } from "#/components/features/manifest/manifest-setup-dialog";+import type { SetupPrerequisitesResult } from "#/hooks/query/use-manifest-prerequisites";+import type { SetupEntry } from "#/manifests/types";+import { createSetupEntry } from "../../manifests/manifest-test-data";++/**+ * The dialog is the part of setup that is not pure: it owns the step order, the+ * local check that has to pass before the service is asked anything, what the+ * action is handed, and where a finished setup lands. Each stage it drives has+ * its own test, so those are stubbed here and only the wiring is exercised.+ */+const mocks = vi.hoisted(() => ({+ navigate: vi.fn(),+ runAction: vi.fn(),+ prerequisites: vi.fn(),+ tracking: {+ trackAutomationSetupOpened: vi.fn(),+ trackAutomationSetupValidated: vi.fn(),+ trackAutomationSetupCreated: vi.fn(),+ trackAutomationSetupFailed: vi.fn(),+ },+}));++vi.mock("react-router", async (importOriginal) => ({+ ...(await importOriginal<typeof import("react-router")>()),+ useNavigate: () => mocks.navigate,+}));++// A local backend, where the repository field is a plain input rather than the+// picker only a cloud backend can populate.+vi.mock("#/contexts/active-backend-context", () => ({+ useActiveBackend: () => ({+ backend: { id: "local-1", kind: "local" },+ orgId: null,+ }),+}));++vi.mock("#/hooks/query/use-manifest-capabilities", () => ({+ useSetupCapabilities: () => ({+ capabilities: null,+ supported: "unknown",+ unmet: [],+ isLoading: false,+ }),+}));++vi.mock("#/hooks/query/use-manifest-prerequisites", () => ({+ useSetupPrerequisites: () => mocks.prerequisites(),+}));++vi.mock("#/manifests/manifest-actions", () => ({+ useSetupAction: () => mocks.runAction,+}));++vi.mock("#/hooks/use-tracking", () => ({+ useTracking: () => mocks.tracking,+}));++vi.mock("#/api/automation-service/automation-service.api", () => ({+ default: { validateDraft: vi.fn() },+}));++const NOTHING_TO_CONNECT: SetupPrerequisitesResult = {+ blockingIntegrations: [],+ warningIntegrations: [],+ isBlocked: false,+ isLoading: false,+};++const ENTRY: SetupEntry = createSetupEntry();++function renderDialog() {+ const user = userEvent.setup();+ render(+ <QueryClientProvider+ client={+ new QueryClient({ defaultOptions: { queries: { retry: false } } })+ }+ >+ <SetupDialog entry={ENTRY} onClose={vi.fn()} />+ </QueryClientProvider>,+ );+ return { user };+}++/** Answer the two required fields the entry ships without a default. */+async function fillForm(user: ReturnType<typeof userEvent.setup>) {+ await user.type(+ screen.getByTestId("setup-field-repository"),+ "OpenHands/agent-server-gui",+ );+ await user.type(screen.getByTestId("setup-field-widgetName"), "Widgets");+}++beforeEach(() => {+ vi.clearAllMocks();+ mocks.prerequisites.mockReturnValue(NOTHING_TO_CONNECT);+ vi.mocked(AutomationService.validateDraft).mockResolvedValue({+ valid: true,+ errors: [],+ });+});++describe("SetupDialog", () => {+ it("asks about an unconnected integration before it asks anything else", async () => {+ // Arrange — an advisory integration, which is shown but does not block.+ mocks.prerequisites.mockReturnValue({+ ...NOTHING_TO_CONNECT,+ warningIntegrations: [+ {+ id: "github",+ requirement: { message: "Used to read widgets.", required: false },+ entry: null,+ },+ ],+ });+ const { user } = renderDialog();++ // Act+ expect(screen.getByTestId("setup-prerequisites")).toBeInTheDocument();+ await user.click(screen.getByTestId("setup-continue-button"));++ // Assert+ expect(screen.getByTestId("setup-field-widgetName")).toBeInTheDocument();+ expect(screen.queryByTestId("setup-prerequisites")).toBeNull();+ });++ it("holds an unanswered required field back from the service", async () => {+ // Arrange — nothing typed, so two required fields are still empty.+ const { user } = renderDialog();++ // Act+ await user.click(screen.getByTestId("setup-continue-button"));++ // Assert — the local check reports the field's own code rather than+ // collapsing every failure into one message, and nothing was sent.+ expect(+ screen.getByTestId("setup-field-widgetName-error"),+ ).toHaveTextContent("SETUP$VALIDATION_REQUIRED");+ expect(AutomationService.validateDraft).not.toHaveBeenCalled();+ expect(screen.queryByTestId("setup-review")).toBeNull();+ });++ it("creates from the derived payload and opens what was created", async () => {+ // Arrange+ mocks.runAction.mockResolvedValue({ response: { id: "automation-1" } });+ const { user } = renderDialog();+ await fillForm(user);++ // Act+ await user.click(screen.getByTestId("setup-continue-button"));+ await waitFor(() =>+ expect(screen.getByTestId("setup-review")).toBeInTheDocument(),+ );+ await user.click(screen.getByTestId("setup-continue-button"));++ // Assert — the action is handed the derived request body, not the raw+ // answers, and the new automation is where setup lands.+ await waitFor(() =>+ expect(mocks.navigate).toHaveBeenCalledWith("/automations/automation-1", {+ replace: true,+ }),+ );+ expect(mocks.runAction.mock.calls[0][2]).toEqual({+ name: "Widget monitor - OpenHands/agent-server-gui",+ prompt: "Report on Widgets in OpenHands/agent-server-gui.",+ repos: [{ url: "OpenHands/agent-server-gui", provider: "github" }],+ trigger: { type: "cron", schedule: "*/15 * * * *" },+ });+ });++ it("returns a rejected create to the field the service blamed", async () => {+ // Arrange — a validation failure addressed by payload path, which only the+ // derived error map can turn back into a field.+ mocks.runAction.mockRejectedValue(+ Object.assign(new Error("Unprocessable Entity"), {+ name: "HttpError",+ status: 422,+ response: {+ detail: [+ {+ loc: ["body", "trigger", "cron", "schedule"],+ msg: "Interval is too short",+ },+ ],+ },+ }),+ );+ const { user } = renderDialog();+ await fillForm(user);++ // Act+ await user.click(screen.getByTestId("setup-continue-button"));+ await waitFor(() =>+ expect(screen.getByTestId("setup-review")).toBeInTheDocument(),+ );+ await user.click(screen.getByTestId("setup-continue-button"));++ // Assert — back on the form, with the message against `schedule` rather+ // than against the form as a whole.+ await waitFor(() =>+ expect(+ screen.getByTestId("setup-field-schedule-error"),+ ).toHaveTextContent("Interval is too short"),+ );+ expect(screen.queryByTestId("setup-review")).toBeNull();+ expect(mocks.navigate).not.toHaveBeenCalled();+ });+});diff --git a/__tests__/constants/extensions-catalogs.test.ts b/__tests__/constants/extensions-catalogs.test.tsindex 985a09ed94..62994dbba2 100644--- a/__tests__/constants/extensions-catalogs.test.ts+++ b/__tests__/constants/extensions-catalogs.test.ts@@ -1,6 +1,8 @@import { describe, expect, it } from "vitest";import { AUTOMATION_CATALOG } from "@openhands/extensions/automations";import { INTEGRATION_CATALOG } from "@openhands/extensions/integrations";+import { SETUP_REGISTRY } from "#/manifests/manifest-sources";+import { getIntegrationIds } from "#/utils/automation-catalog";import {getDefaultMcpTransport,getInstallableMcpConnectionOption,@@ -69,10 +71,23 @@ describe("OpenHands extensions catalogs", () => {const knownMcpIds = new Set(INTEGRATION_CATALOG.map((entry) => entry.id));for (const automation of AUTOMATION_CATALOG) {- expect(automation.requiredIntegrationIds.length).toBeGreaterThan(0);- expect(- automation.requiredIntegrationIds.every((id) => knownMcpIds.has(id)),- ).toBe(true);+ const integrationIds = getIntegrationIds(automation);+ expect(integrationIds.length).toBeGreaterThan(0);+ expect(integrationIds.every((id) => knownMcpIds.has(id))).toBe(true);}});++ it("admits every setup experience the automation catalog ships", () => {+ // Arrange — the pinned package is the whole source of setup manifests, and+ // a shipped one that fails admission is dropped silently.+ const shipped = AUTOMATION_CATALOG.filter(+ (automation) => !!automation.setup,+ );+ expect(shipped.length).toBeGreaterThan(0);++ // Act / Assert+ expect(SETUP_REGISTRY.entries.map((entry) => entry.id)).toEqual(+ shipped.map((automation) => automation.id),+ );+ });});diff --git a/__tests__/hooks/query/use-manifest-prerequisites.test.tsx b/__tests__/hooks/query/use-manifest-prerequisites.test.tsxnew file mode 100644index 0000000000..ef7f296d45--- /dev/null+++ b/__tests__/hooks/query/use-manifest-prerequisites.test.tsx@@ -0,0 +1,104 @@+import React from "react";+import { describe, expect, it, vi, beforeEach } from "vitest";+import { renderHook, waitFor } from "@testing-library/react";+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";+import { useSetupPrerequisites } from "#/hooks/query/use-manifest-prerequisites";+import SettingsService from "#/api/settings-service/settings-service.api";+import { createSetupEntry } from "../../manifests/manifest-test-data";+import type { SetupEntry } from "#/manifests/types";++vi.mock("#/api/settings-service/settings-service.api", () => ({+ default: { getSettings: vi.fn() },+}));++vi.mock("#/contexts/active-backend-context", () => ({+ useActiveBackend: () => ({+ backend: { id: "test-backend", kind: "local" },+ orgId: null,+ }),+}));++/** The endpoint the packaged GitHub integration is installed against. */+const GITHUB_MCP_URL = "https://api.githubcopilot.com/mcp/";++function createWrapper() {+ const queryClient = new QueryClient({+ defaultOptions: { queries: { retry: false } },+ });+ return ({ children }: { children: React.ReactNode }) => (+ <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>+ );+}++function withIntegrations(+ integrations: SetupEntry["requires"]["integrations"],+): SetupEntry {+ return createSetupEntry({ requires: { integrations } });+}++function renderPrerequisites(entry: SetupEntry) {+ return renderHook(() => useSetupPrerequisites(entry), {+ wrapper: createWrapper(),+ });+}++describe("useSetupPrerequisites", () => {+ beforeEach(() => {+ vi.clearAllMocks();+ // Nothing connected, unless a test says otherwise.+ vi.mocked(SettingsService.getSettings).mockResolvedValue({} as never);+ });++ it("blocks setup while a required integration is not connected", async () => {+ // Arrange+ const entry = withIntegrations({+ github: { message: "Reads pull requests." },+ });++ // Act+ const { result } = renderPrerequisites(entry);++ // Assert+ await waitFor(() => expect(result.current.isLoading).toBe(false));+ expect(result.current.isBlocked).toBe(true);+ });++ it("lets setup continue when an unconnected integration is only advisory", async () => {+ // Arrange+ const entry = withIntegrations({+ notion: { message: "Publishes the result.", required: false },+ });++ // Act+ const { result } = renderPrerequisites(entry);++ // Assert+ await waitFor(() => expect(result.current.isLoading).toBe(false));+ expect({+ isBlocked: result.current.isBlocked,+ warned: result.current.warningIntegrations.map(({ id }) => id),+ }).toEqual({ isBlocked: false, warned: ["notion"] });+ });++ it("has nothing to block on once the integration is connected", async () => {+ // Arrange+ vi.mocked(SettingsService.getSettings).mockResolvedValue({+ agent_settings: {+ mcp_config: { mcpServers: { github: { url: GITHUB_MCP_URL } } },+ },+ } as never);+ const entry = withIntegrations({+ github: { message: "Reads pull requests." },+ });++ // Act+ const { result } = renderPrerequisites(entry);++ // Assert+ await waitFor(() => expect(result.current.isLoading).toBe(false));+ expect({+ isBlocked: result.current.isBlocked,+ blocking: result.current.blockingIntegrations,+ }).toEqual({ isBlocked: false, blocking: [] });+ });+});diff --git a/__tests__/hooks/use-manifest-preflight.test.tsx b/__tests__/hooks/use-manifest-preflight.test.tsxnew file mode 100644index 0000000000..3d27255e27--- /dev/null+++ b/__tests__/hooks/use-manifest-preflight.test.tsx@@ -0,0 +1,77 @@+import { renderHook } from "@testing-library/react";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import AutomationService from "#/api/automation-service/automation-service.api";+import { useSetupPreflight } from "#/hooks/use-manifest-preflight";+import { createSetupEntry } from "../manifests/manifest-test-data";++vi.mock("#/api/automation-service/automation-service.api", () => ({+ default: { validateDraft: vi.fn() },+}));++/** A local call's failure, which arrives as an `AxiosError`. */+function axiosFailure(status: number) {+ return Object.assign(new Error(`Request failed with status ${status}`), {+ isAxiosError: true,+ response: { status },+ });+}++/** A cloud call's failure, which arrives as the shared client's `HttpError`. */+function httpFailure(status: number) {+ return Object.assign(new Error(`Request failed with status ${status}`), {+ name: "HttpError",+ status,+ });+}++const ENTRY = createSetupEntry();+const VALUES = { repository: "OpenHands/agent-server-gui", widgetName: "W" };++function runPreflightAgainst(error: unknown) {+ vi.mocked(AutomationService.validateDraft).mockRejectedValue(error);+ const { result } = renderHook(() => useSetupPreflight(ENTRY));+ return result.current(VALUES);+}++let warn: ReturnType<typeof vi.spyOn>;++beforeEach(() => {+ vi.clearAllMocks();+ warn = vi.spyOn(console, "warn").mockImplementation(() => {});+});++afterEach(() => {+ warn.mockRestore();+});++describe("useSetupPreflight", () => {+ it.each([+ ["a local deployment without the route", axiosFailure(404)],+ ["a cloud deployment that has not implemented it", httpFailure(501)],+ ])("has no verdict and nothing to report for %s", async (_case, error) => {+ // Act+ const result = await runPreflightAgainst(error);++ // Assert — preflight is advisory, and an absent endpoint is an expected+ // state rather than something worth reporting.+ expect(result).toBeNull();+ expect(warn).not.toHaveBeenCalled();+ });++ it.each([+ ["a validator that is failing", httpFailure(500)],+ ["a rejected session", axiosFailure(401)],+ ["a request that never got a response", new Error("Network Error")],+ ])("reports %s while still letting setup continue", async (_case, error) => {+ // Act+ const result = await runPreflightAgainst(error);++ // Assert — the user is not blocked, but the failure is not invisible+ // either; without this it reads exactly like an unimplemented endpoint.+ expect(result).toBeNull();+ expect(warn).toHaveBeenCalledWith(+ "Automation setup preflight failed:",+ error,+ );+ });+});diff --git a/__tests__/manifests/automation-setup.test.ts b/__tests__/manifests/automation-setup.test.tsnew file mode 100644index 0000000000..74501f9780--- /dev/null+++ b/__tests__/manifests/automation-setup.test.ts@@ -0,0 +1,364 @@+import { describe, expect, it, vi } from "vitest";+import {+ buildAssistedMessage,+ buildCreatePayload,+ buildPreflightBody,+ deriveErrorMap,+} from "#/manifests/automation-setup";+import { validateSetupEntry } from "#/manifests/manifest-validation";+import type { SetupEntry } from "#/manifests/types";++// The command a skill publishes in its own frontmatter, which the host looks up+// rather than storing. Pinned here so the assertion does not move when the+// packaged catalog does.+vi.mock("@openhands/extensions/skills", () => ({+ SKILLS_CATALOG: [+ {+ name: "incident-retrospective",+ description: "Draft an incident retrospective.",+ triggers: ["/incident-retro:setup"],+ content: "",+ },+ ],+}));++/**+ * The setup blocks published in `OpenHands/extensions`, and the request bodies+ * its contract fixtures say they must produce. Those bodies were verified+ * against the live service, and the create model forbids extra keys, so any+ * divergence here is a 422 in production rather than a cosmetic difference.+ */+const PR_REVIEWER: SetupEntry = {+ id: "github-pr-reviewer",+ name: "GitHub Code Review Agent",+ description: "Watch for a configurable label on GitHub pull requests.",+ requires: {+ integrations: {+ github: { message: "Used to read pull requests and post comments." },+ },+ features: ["repoClone", "presetPrompt"],+ },+ setup: {+ version: "1.0",+ mode: "direct",+ form: {+ triggers: {+ cron: {+ schedule: {+ type: "cron",+ label: "Check frequency",+ help: "How often to look for newly labelled pull requests.",+ default: "*/15 * * * *",+ required: true,+ },+ timezone: {+ type: "timezone",+ label: "Timezone",+ help: "Timezone the schedule is interpreted in.",+ default: "UTC",+ required: true,+ },+ },+ },+ args: {+ repository: {+ type: "repo-picker",+ label: "Repository",+ help: "The repository whose pull requests will be reviewed.",+ provider: "github",+ required: true,+ },+ triggerLabel: {+ type: "text",+ label: "Trigger label",+ help: "Only pull requests carrying this label are reviewed.",+ default: "openhands-review",+ required: true,+ constraints: { minLength: 1, maxLength: 50 },+ },+ reviewTone: {+ type: "select",+ label: "Review tone",+ help: "How detailed the review comments should be.",+ default: "concise",+ required: true,+ options: [+ { value: "concise", label: "Concise" },+ { value: "thorough", label: "Thorough" },+ ],+ },+ },+ },+ prompt:+ "Review pull requests labeled '{{form.triggerLabel}}' in {{form.repository}}. Review tone: {{form.reviewTone}}.",+ },+};++const REPO_MONITOR: SetupEntry = {+ id: "github-repo-monitor",+ name: "GitHub repository monitor",+ description: "Watch a repository for @OpenHands mentions.",+ requires: {+ integrations: {+ github: { message: "Used to read comments and post replies." },+ },+ features: ["repoClone", "presetPrompt", "webhookDelivery"],+ },+ setup: {+ version: "1.0",+ mode: "direct",+ form: {+ triggers: {+ event: {+ on: {+ type: "select",+ label: "Respond to",+ help: "Which GitHub comment event starts a conversation.",+ default: "issue_comment.created",+ required: true,+ options: [+ {+ value: "issue_comment.created",+ label: "Comments on issues and pull requests",+ },+ {+ value: "pull_request_review_comment.created",+ label: "Pull request review comments only",+ },+ ],+ },+ triggerPhrase: {+ type: "text",+ label: "Trigger phrase",+ help: "Only comments containing this phrase start a conversation.",+ default: "@openhands",+ required: true,+ constraints: {+ minLength: 2,+ maxLength: 50,+ format: "safeExpressionLiteral",+ },+ },+ },+ },+ args: {+ repository: {+ type: "repo-picker",+ label: "Repository",+ help: "The repository or repositories to watch for mentions.",+ provider: "github",+ required: true,+ },+ ref: {+ type: "text",+ label: "Base branch",+ help: "Branch checked out when the agent responds.",+ default: "main",+ required: true,+ constraints: { minLength: 1, maxLength: 255 },+ },+ },+ },+ prompt:+ "A comment in {{form.repository}} mentions '{{form.triggerPhrase}}'. Read the surrounding issue or pull request context from the event payload, then post a helpful reply as a comment on the same thread.",+ filter:+ "icontains(comment.body, '{{form.triggerPhrase}}') && glob(repository.full_name, '{{form.repository}}')",+ },+};++const RETRO_DRAFTER: SetupEntry = {+ id: "incident-retrospective-drafter",+ name: "Incident retrospective drafter",+ description: "Collect incident chatter and draft a timeline.",+ requires: {+ integrations: {+ slack: { message: "Reads incident discussion and timestamps." },+ linear: { message: "Reads follow-up tickets, owners, and status." },+ notion: {+ message: "Publishes the drafted retrospective.",+ required: false,+ },+ },+ features: ["mcpTools", "conversationDispatch"],+ },+ skill: "incident-retrospective",+ setup: {+ version: "1.0",+ mode: "assisted",+ form: {+ note: "These answers start the conversation.",+ args: {+ incidentChannel: {+ type: "text",+ label: "Incident channel",+ help: "The Slack channel where incidents are discussed.",+ 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.",+ required: false,+ constraints: { maxLength: 200 },+ },+ triggerPreference: {+ type: "select",+ label: "How should it run?",+ help: "A starting preference only.",+ default: "undecided",+ required: false,+ options: [+ { value: "undecided", label: "Let the agent recommend one" },+ { value: "scheduled", label: "On a schedule" },+ ],+ },+ notes: {+ type: "textarea",+ label: "Anything else the agent should know?",+ help: "Incident naming conventions, 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.",+ },+};++const PR_REVIEWER_VALUES = {+ repository: "OpenHands/agent-server-gui",+ triggerLabel: "openhands-review",+ reviewTone: "thorough",+ schedule: "*/15 * * * *",+ timezone: "UTC",+};++const PR_REVIEWER_DRAFT = {+ name: "GitHub Code Review Agent - OpenHands/agent-server-gui",+ prompt:+ "Review pull requests labeled 'openhands-review' in OpenHands/agent-server-gui. Review tone: thorough.",+ repos: [{ url: "OpenHands/agent-server-gui", provider: "github" }],+ trigger: { type: "cron", schedule: "*/15 * * * *", timezone: "UTC" },+};++describe("buildCreatePayload", () => {+ it("derives the scheduled request body the contract fixture pins", () => {+ // Act+ const payload = buildCreatePayload(PR_REVIEWER, PR_REVIEWER_VALUES);++ // Assert+ expect(payload).toEqual(PR_REVIEWER_DRAFT);+ });++ it("derives an event trigger's source and filter, which no manifest states", () => {+ // Act+ const payload = buildCreatePayload(REPO_MONITOR, {+ repository: "OpenHands/agent-server-gui",+ triggerPhrase: "@openhands",+ on: "issue_comment.created",+ ref: "main",+ });++ // Assert+ expect(payload).toEqual({+ name: "GitHub repository monitor - OpenHands/agent-server-gui",+ prompt:+ "A comment in OpenHands/agent-server-gui mentions '@openhands'. Read the surrounding issue or pull request context from the event payload, then post a helpful reply as a comment on the same thread.",+ repos: [+ {+ url: "OpenHands/agent-server-gui",+ ref: "main",+ provider: "github",+ },+ ],+ trigger: {+ type: "event",+ source: "github",+ on: "issue_comment.created",+ filter:+ "icontains(comment.body, '@openhands') && glob(repository.full_name, 'OpenHands/agent-server-gui')",+ },+ });+ });++ it("sends no request body for an entry that hands setup to a conversation", () => {+ // Act+ const payload = buildCreatePayload(RETRO_DRAFTER, {});++ // Assert+ expect(payload).toBeNull();+ });+});++describe("buildPreflightBody", () => {+ it("wraps the draft in the envelope the validate endpoint expects", () => {+ // Act+ const body = buildPreflightBody(PR_REVIEWER, PR_REVIEWER_VALUES);++ // Assert+ expect(body).toEqual({+ automationId: "github-pr-reviewer",+ endpoint: "/v1/preset/prompt",+ draft: PR_REVIEWER_DRAFT,+ });+ });+});++describe("deriveErrorMap", () => {+ it("recovers which fields built each payload path", () => {+ // Act+ const errorMap = deriveErrorMap(PR_REVIEWER);++ // Assert+ expect(errorMap).toEqual({+ name: ["repository"],+ prompt: ["triggerLabel", "repository", "reviewTone"],+ "repos[0].url": ["repository"],+ "trigger.schedule": ["schedule"],+ "trigger.timezone": ["timezone"],+ });+ });+});++describe("buildAssistedMessage", () => {+ it("opens with the owning skill's command and the interpolated answers", () => {+ // Act+ const message = buildAssistedMessage(RETRO_DRAFTER, {+ incidentChannel: "#incidents",+ linearTeam: "Reliability",+ notionDestination: "",+ triggerPreference: "undecided",+ notes: "",+ });++ // Assert+ expect(message).toBe(+ "/incident-retro:setup\n\nThe user supplied these starting points. Confirm each one, ask about anything left blank, then create the automation.\n\n- Incident channel: #incidents\n- Linear team: Reliability\n- Notion destination: \n- Preferred trigger: undecided\n- Notes: \n\nStill undecided and required before creation: the incident identifier format and the approved Notion retrospective template.",+ );+ });+});++describe("the published manifests", () => {+ // The host enforces invariants its own derivation depends on, which the+ // published schema does not. Every shipped entry has to satisfy them too.+ it.each([+ ["github-pr-reviewer", PR_REVIEWER],+ ["github-repo-monitor", REPO_MONITOR],+ ["incident-retrospective-drafter", RETRO_DRAFTER],+ ])("admits %s", (_id, entry) => {+ // Act+ const result = validateSetupEntry(entry);++ // Assert+ expect(result).toEqual({ valid: true, errors: [] });+ });+});diff --git a/__tests__/manifests/manifest-capabilities.test.ts b/__tests__/manifests/manifest-capabilities.test.tsnew file mode 100644index 0000000000..261f6aba37--- /dev/null+++ b/__tests__/manifests/manifest-capabilities.test.ts@@ -0,0 +1,79 @@+import { describe, expect, it } from "vitest";+import { assessCapabilityRequirements } from "#/manifests/manifest-capabilities";+import type { DeploymentCapabilities } from "#/manifests/types";+import { createSetup, createSetupEntry } from "./manifest-test-data";++const READY_DEPLOYMENT: DeploymentCapabilities = {+ ready: true,+ triggerKinds: ["cron"],+ eventSources: [],+ eventTypes: [],+ triggers: { cron: { minIntervalSeconds: 60, timezones: ["UTC"] } },+ features: ["repoClone", "presetPrompt"],+};++describe("assessCapabilityRequirements", () => {+ it("supports a manifest whose every requirement the deployment reports", () => {+ // Arrange+ const entry = createSetupEntry({+ requires: {+ integrations: { github: { message: "Used to read widgets." } },+ features: ["repoClone"],+ },+ });++ // Act+ const assessment = assessCapabilityRequirements(entry, READY_DEPLOYMENT);++ // Assert+ expect(assessment).toEqual({ supported: true, unmet: [] });+ });++ it("names every requirement the deployment left unreported", () => {+ // Arrange — the `cronOnly` deployment shape: reachable and ready, but no+ // webhooks can be delivered to it, so it offers neither the feature nor+ // the trigger kind an event-driven entry needs.+ const entry = createSetupEntry({+ requires: {+ integrations: { github: { message: "Used to read widgets." } },+ features: ["repoClone", "webhookDelivery"],+ },+ setup: createSetup({+ form: {+ triggers: {+ event: {+ on: {+ type: "select",+ label: "Respond to",+ help: "Which event.",+ required: true,+ options: [{ value: "push", label: "Push" }],+ },+ },+ },+ args: {},+ },+ }),+ });++ // Act+ const assessment = assessCapabilityRequirements(entry, READY_DEPLOYMENT);++ // Assert — both names, so the block can say what is missing.+ expect(assessment).toEqual({+ supported: false,+ unmet: ["webhookDelivery", "event"],+ });+ });++ it("does not support any manifest while the deployment reports it is not ready", () => {+ // Act+ const assessment = assessCapabilityRequirements(createSetupEntry(), {+ ...READY_DEPLOYMENT,+ ready: false,+ });++ // Assert — no single requirement is the reason, so none is named.+ expect(assessment).toEqual({ supported: false, unmet: [] });+ });+});diff --git a/__tests__/manifests/manifest-error-map.test.ts b/__tests__/manifests/manifest-error-map.test.tsnew file mode 100644index 0000000000..64f9295cdd--- /dev/null+++ b/__tests__/manifests/manifest-error-map.test.ts@@ -0,0 +1,121 @@+import { describe, expect, it } from "vitest";+import {+ mapServiceErrors,+ normalizeServiceErrors,+} from "#/manifests/manifest-error-map";++/** The body the host derived, as the service received it. */+const PAYLOAD = {+ name: "PR Reviewer - OpenHands/agent-server-gui",+ prompt: "Review pull requests labeled 'openhands-review'.",+ repos: [{ url: "OpenHands/agent-server-gui", ref: "main" }],+ trigger: { type: "cron", schedule: "0 0 31 2 *", timezone: "UTC" },+};++/** As `deriveErrorMap` produces it: every path maps to the fields that built it. */+const ERROR_MAP = {+ "repos[0].ref": ["ref"],+ "trigger.schedule": ["schedule"],+ prompt: ["triggerLabel", "reviewTone"],+};++describe("normalizeServiceErrors", () => {+ it("reads field-addressed errors out of a preflight result", () => {+ // Act+ const errors = normalizeServiceErrors(+ {+ valid: false,+ errors: [+ {+ field: "trigger.schedule",+ message: "Minimum interval for this deployment is 5 minutes.",+ },+ ],+ },+ PAYLOAD,+ );++ // Assert+ expect(errors).toEqual([+ {+ path: "trigger.schedule",+ message: "Minimum interval for this deployment is 5 minutes.",+ },+ ]);+ });++ it("resolves a rejection addressed through a discriminated union", () => {+ // The service names the branch it validated against — `trigger.cron` —+ // but the body it received has no `cron` key. Walking the payload and+ // skipping segments that do not resolve reduces the address to one the+ // manifest can map, without the host knowing what a trigger is.++ // Act+ const errors = normalizeServiceErrors(+ {+ detail: [+ {+ loc: ["body", "trigger", "cron", "schedule"],+ msg: "Cron expression cannot produce any future fire times.",+ },+ ],+ },+ PAYLOAD,+ );++ // Assert+ expect(errors[0].path).toBe("trigger.schedule");+ });++ it("addresses an element of a list by its index", () => {+ // Act+ const errors = normalizeServiceErrors(+ { detail: [{ loc: ["body", "repos", 0, "ref"], msg: "Unknown ref." }] },+ PAYLOAD,+ );++ // Assert+ expect(errors[0].path).toBe("repos[0].ref");+ });+});++describe("mapServiceErrors", () => {+ it("highlights the field that produced the rejected value", () => {+ // Act+ const { fieldErrors } = mapServiceErrors(+ [{ path: "trigger.schedule", message: "Too frequent." }],+ ERROR_MAP,+ );++ // Assert+ expect(fieldErrors).toEqual({ schedule: "Too frequent." });+ });++ it("highlights every field that contributed to a combined value", () => {+ // Act+ const { fieldErrors } = mapServiceErrors(+ [{ path: "prompt", message: "Prompt is too long." }],+ ERROR_MAP,+ );++ // Assert+ expect(fieldErrors).toEqual({+ triggerLabel: "Prompt is too long.",+ reviewTone: "Prompt is too long.",+ });+ });++ it("surfaces an unmappable rejection against the form rather than losing it", () => {+ // Act+ const { fieldErrors, formErrors } = mapServiceErrors(+ [{ path: "tarball_path", message: "Upload failed." }],+ ERROR_MAP,+ );++ // Assert+ expect({ fieldErrors, formErrors }).toEqual({+ fieldErrors: {},+ formErrors: ["Upload failed."],+ });+ });+});diff --git a/__tests__/manifests/manifest-local-validation.test.ts b/__tests__/manifests/manifest-local-validation.test.tsnew file mode 100644index 0000000000..1aa1583a4e--- /dev/null+++ b/__tests__/manifests/manifest-local-validation.test.ts@@ -0,0 +1,143 @@+import { describe, expect, it } from "vitest";+import {+ getFieldOptions,+ getInitialFormValues,+ resolveFieldOverrides,+ validateFormValues,+} from "#/manifests/manifest-local-validation";+import type { DeploymentCapabilities } from "#/manifests/types";+import { createSetup } from "./manifest-test-data";++const SETUP = createSetup({+ form: {+ args: {+ widgetName: {+ type: "text",+ label: "Widget name",+ help: "What to call it.",+ required: true,+ constraints: { maxLength: 10 },+ },+ matchPhrase: {+ type: "text",+ label: "Match phrase",+ help: "Becomes part of a filter expression.",+ required: false,+ constraints: { format: "safeExpressionLiteral" },+ },+ size: {+ type: "select",+ label: "Size",+ help: "How big.",+ default: "small",+ required: false,+ options: [{ value: "small", label: "Small" }],+ },+ timezone: {+ type: "timezone",+ label: "Timezone",+ help: "Which zone the schedule is read in.",+ required: false,+ },+ },+ },+});++describe("validateFormValues", () => {+ it("reports a required field the user left blank", () => {+ // Act+ const errors = validateFormValues(SETUP, { widgetName: " " });++ // Assert+ expect(errors.widgetName).toEqual({ code: "required" });+ });++ it("reports a value longer than the manifest allows", () => {+ // Act+ const errors = validateFormValues(SETUP, {+ widgetName: "a-very-long-widget-name",+ });++ // Assert+ expect(errors.widgetName).toEqual({ code: "maxLength", length: 10 });+ });++ it("rejects characters that would break out of an expression literal", () => {+ // Act+ const errors = validateFormValues(SETUP, {+ widgetName: "ok",+ matchPhrase: 'he said "hi"',+ });++ // Assert+ expect(errors.matchPhrase).toEqual({ code: "unsafeExpressionLiteral" });+ });++ it("rejects a choice that is not on offer", () => {+ // Act+ const errors = validateFormValues(SETUP, {+ widgetName: "ok",+ size: "enormous",+ });++ // Assert+ expect(errors.size).toEqual({ code: "invalidOption" });+ });++ it("passes a form that satisfies every declared constraint", () => {+ // Act+ const errors = validateFormValues(SETUP, {+ widgetName: "ok",+ matchPhrase: "ship it",+ size: "small",+ });++ // Assert+ expect(errors).toEqual({});+ });+});++describe("deployment-supplied constraints", () => {+ it("offers the timezones the deployment reports, which no manifest declares", () => {+ // Arrange — the accepted zones belong to the deployment, not the manifest.+ const capabilities = {+ triggers: { cron: { minIntervalSeconds: 60, timezones: ["UTC", "CET"] } },+ } as DeploymentCapabilities;++ // Act+ const overrides = resolveFieldOverrides(SETUP, capabilities);++ // Assert+ expect(+ getFieldOptions("timezone", SETUP.form.args.timezone, overrides),+ ).toEqual([+ { value: "UTC", label: "UTC" },+ { value: "CET", label: "CET" },+ ]);+ });++ it("keeps the manifest's own options when the deployment cannot be asked", () => {+ // Act+ const overrides = resolveFieldOverrides(SETUP, null);++ // Assert+ expect(getFieldOptions("size", SETUP.form.args.size, overrides)).toEqual(+ SETUP.form.args.size.options,+ );+ });+});++describe("getInitialFormValues", () => {+ it("seeds every declared field with its declared default", () => {+ // Act+ const values = getInitialFormValues(SETUP);++ // Assert+ expect(values).toEqual({+ widgetName: "",+ matchPhrase: "",+ size: "small",+ timezone: "",+ });+ });+});diff --git a/__tests__/manifests/manifest-registry.test.ts b/__tests__/manifests/manifest-registry.test.tsnew file mode 100644index 0000000000..a202345a3a--- /dev/null+++ b/__tests__/manifests/manifest-registry.test.ts@@ -0,0 +1,77 @@+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import { createSetupRegistry } from "#/manifests/manifest-registry";+import {+ createSetup,+ createSetupEntry,+ createSetupEntryWith,+} from "./manifest-test-data";++describe("createSetupRegistry", () => {+ beforeEach(() => {+ // Rejections are reported for the manifest author, not the user.+ vi.spyOn(console, "warn").mockImplementation(() => {});+ });++ afterEach(() => {+ vi.restoreAllMocks();+ });++ it("resolves an admitted manifest by its id", () => {+ // Arrange+ const entry = createSetupEntry();+ const registry = createSetupRegistry([entry]);++ // Act+ const resolved = registry.findById("widget-monitor");++ // Assert+ expect(resolved).toBe(entry);+ });++ it("claims no id the catalog did not offer", () => {+ // Arrange+ const registry = createSetupRegistry([createSetupEntry()]);++ // Act+ const resolved = registry.findById("something-else");++ // Assert+ expect(resolved).toBeNull();+ });++ it("passes over a catalog entry that ships no setup experience", () => {+ // Arrange — a card-only entry is the normal case, not a rejection.+ const cardOnly = { id: "card-only", name: "Card only" };++ // Act+ const registry = createSetupRegistry([cardOnly, createSetupEntry()]);++ // Assert+ expect(registry.entries).toHaveLength(1);+ });++ it("drops a manifest that fails admission instead of rendering part of it", () => {+ // Arrange+ const rejected = createSetupEntryWith({+ setup: createSetup({ version: "2.0" as "1.0" }),+ });++ // Act+ const registry = createSetupRegistry([rejected, createSetupEntry()]);++ // Assert+ expect(registry.entries).toHaveLength(1);+ });++ it("keeps the first claim on an id so a later manifest cannot hijack it", () => {+ // Arrange+ const first = createSetupEntry({ name: "First" });+ const second = createSetupEntry({ name: "Second" });++ // Act+ const registry = createSetupRegistry([first, second]);++ // Assert+ expect(registry.findById("widget-monitor")).toBe(first);+ });+});diff --git a/__tests__/manifests/manifest-test-data.ts b/__tests__/manifests/manifest-test-data.tsnew file mode 100644index 0000000000..552cd38b88--- /dev/null+++ b/__tests__/manifests/manifest-test-data.ts@@ -0,0 +1,67 @@+import type { SetupBlock, SetupEntry } from "#/manifests/types";++/**+ * A minimal catalog entry the host will admit.+ *+ * Tests override only the part they exercise. The three published entries live+ * in `automation-setup.test.ts`, where the derived request bodies are pinned+ * against the contract fixtures.+ */+export function createSetupEntry(+ overrides: Partial<SetupEntry> = {},+): SetupEntry {+ return {+ id: "widget-monitor",+ name: "Widget monitor",+ description: "Watch widgets and report on them.",+ requires: {+ integrations: { github: { message: "Used to read widgets." } },+ },+ setup: createSetup(),+ ...overrides,+ };+}++export function createSetup(overrides: Partial<SetupBlock> = {}): SetupBlock {+ return {+ version: "1.0",+ mode: "direct",+ form: {+ triggers: {+ cron: {+ schedule: {+ type: "cron",+ label: "Check frequency",+ help: "How often to look.",+ default: "*/15 * * * *",+ required: true,+ },+ },+ },+ args: {+ repository: {+ type: "repo-picker",+ label: "Repository",+ help: "Which repository to watch.",+ provider: "github",+ required: true,+ },+ widgetName: {+ type: "text",+ label: "Widget name",+ help: "What to call it.",+ required: true,+ },+ },+ },+ prompt: "Report on {{form.widgetName}} in {{form.repository}}.",+ ...overrides,+ };+}++/** Build a candidate that is invalid in one specific way. */+export function createSetupEntryWith(+ overrides: Record<string, unknown>,+): unknown {+ return { ...createSetupEntry(), ...overrides };+}diff --git a/__tests__/manifests/manifest-validation.test.ts b/__tests__/manifests/manifest-validation.test.tsnew file mode 100644index 0000000000..61ba6b9f5d--- /dev/null+++ b/__tests__/manifests/manifest-validation.test.ts@@ -0,0 +1,160 @@+import { describe, expect, it } from "vitest";+import { validateSetupEntry } from "#/manifests/manifest-validation";+import {+ createSetup,+ createSetupEntry,+ createSetupEntryWith,+} from "./manifest-test-data";++describe("validateSetupEntry", () => {+ it("admits a well-formed manifest", () => {+ // Arrange+ const entry = createSetupEntry();++ // Act+ const result = validateSetupEntry(entry);++ // Assert+ expect(result).toEqual({ valid: true, errors: [] });+ });++ // Each case is a separate invariant the host enforces on data authored in+ // another repository. A manifest that trips any of them must not render.+ it.each([+ [+ "a setup version this host cannot interpret",+ { setup: createSetup({ version: "2.0" as "1.0" }) },+ ],+ [+ "markup inside user-visible copy",+ { description: "<img src=x onerror=alert(1)>" },+ ],+ [+ "a placeholder namespace the host does not expose",+ { setup: createSetup({ prompt: "Use {{secrets.githubToken}}." }) },+ ],+ [+ "an assisted message on an entry that sends a request",+ { setup: createSetup({ message: "Finish setup with the agent." }) },+ ],+ [+ // The host reads one trigger kind to build the request, so a second one+ // would be silently dropped rather than refused.+ "more trigger kinds than the host can send",+ {+ setup: createSetup({+ form: {+ triggers: {+ cron: {+ schedule: {+ type: "cron",+ label: "Frequency",+ help: "How often.",+ required: true,+ },+ },+ event: {+ on: {+ type: "select",+ label: "Respond to",+ help: "Which event.",+ required: true,+ options: [{ value: "push", label: "Push" }],+ },+ },+ },+ args: {+ repository: {+ type: "repo-picker",+ label: "Repository",+ help: "Which repository.",+ provider: "github",+ required: true,+ },+ },+ },+ }),+ },+ ],+ [+ // An event trigger's source is read off the repository field's provider.+ "an event trigger with no repository field to take its source from",+ {+ setup: createSetup({+ form: {+ triggers: {+ event: {+ on: {+ type: "select",+ label: "Respond to",+ help: "Which event.",+ required: true,+ options: [{ value: "push", label: "Push" }],+ },+ },+ },+ args: {+ widgetName: {+ type: "text",+ label: "Widget name",+ help: "What to call it.",+ required: true,+ },+ },+ },+ filter: "icontains(body, '{{form.widgetName}}')",+ }),+ },+ ],+ [+ // Both halves merge into one value map, so a repeat would shadow a field+ // and misaddress every error reported against it.+ "a field name declared in both halves of the form",+ {+ setup: createSetup({+ form: {+ triggers: {+ cron: {+ repository: {+ type: "text",+ label: "Repository",+ help: "Shadows the argument below.",+ required: true,+ },+ },+ },+ args: {+ repository: {+ type: "repo-picker",+ label: "Repository",+ help: "Which repository to watch.",+ provider: "github",+ required: true,+ },+ },+ },+ }),+ },+ ],+ ])("refuses %s", (_case, overrides) => {+ // Arrange+ const candidate = createSetupEntryWith(overrides);++ // Act+ const result = validateSetupEntry(candidate);++ // Assert+ expect(result.valid).toBe(false);+ });++ it("reports every problem at once so an author sees the whole picture", () => {+ // Arrange+ const candidate = createSetupEntryWith({ name: "", description: "" });++ // Act+ const { errors } = validateSetupEntry(candidate);++ // Assert+ expect(errors).toHaveLength(2);+ });+});diff --git a/__tests__/routes/automation-setup-route.test.ts b/__tests__/routes/automation-setup-route.test.tsnew file mode 100644index 0000000000..6b255253a8--- /dev/null+++ b/__tests__/routes/automation-setup-route.test.ts@@ -0,0 +1,20 @@+import { describe, expect, it } from "vitest";+import routes from "#/routes";++describe("automation setup route", () => {+ it("claims the path an automation card links to", () => {+ // Arrange — a card that ships a setup experience links to+ // `/automations/new/<id>`, so a route has to serve that shape.+ const rootLayout = routes.find(+ (route) => route.file === "routes/root-layout.tsx",+ );++ // Act+ const setupRoute = rootLayout?.children?.find(+ (route) => route.file === "routes/automation-setup-route.tsx",+ );++ // Assert+ expect(setupRoute?.path).toBe("automations/new/:automationId");+ });+});diff --git a/__tests__/utils/automation-catalog.test.ts b/__tests__/utils/automation-catalog.test.tsnew file mode 100644index 0000000000..caad6862df--- /dev/null+++ b/__tests__/utils/automation-catalog.test.ts@@ -0,0 +1,29 @@+import { describe, expect, it } from "vitest";+import { AUTOMATION_CATALOG } from "@openhands/extensions/automations";+import { getAutomationLaunchPrompt } from "#/utils/automation-catalog";++const automationById = (id: string) =>+ AUTOMATION_CATALOG.find((automation) => automation.id === id)!;++describe("getAutomationLaunchPrompt", () => {+ it("resolves the command from the skill that implements the automation", () => {+ // Arrange / Act / Assert — an entry whose skill is its own id, and one+ // that names a different skill, both resolve to that skill's command.+ expect(+ getAutomationLaunchPrompt(automationById("github-pr-reviewer")),+ ).toBe("/pr-reviewer:setup");+ expect(+ getAutomationLaunchPrompt(+ automationById("incident-retrospective-drafter"),+ ),+ ).toBe("/incident-retro:setup");+ });++ it("spells the request out when the skill declares no command", () => {+ // Arrange / Act / Assert — `jira-issue-to-pr` is invoked by description,+ // so there is no trigger to resolve.+ expect(getAutomationLaunchPrompt(automationById("jira-issue-to-pr"))).toBe(+ "Set up the Jira issue to GitHub PR automation",+ );+ });+});diff --git a/__tests__/utils/responder-deployment.test.ts b/__tests__/utils/responder-deployment.test.tsindex eea1c128f6..ea1cb22604 100644--- a/__tests__/utils/responder-deployment.test.ts+++ b/__tests__/utils/responder-deployment.test.ts@@ -30,6 +30,23 @@ describe("isResponderAutomation", () => {isResponderAutomation(automationById("linear-triage-assistant")),).toBe(false);});++ it("ignores an integration the automation can start without", () => {+ // Arrange — a GitHub responder that also publishes to Notion, but is+ // willing to run before Notion is connected.+ const automation = {+ ...automationById("github-pr-reviewer"),+ requires: {+ integrations: {+ github: { message: "Reads pull requests." },+ notion: { message: "Publishes a summary.", required: false as const },+ },+ },+ };++ // Act / Assert — where it runs is decided by what it needs.+ expect(isResponderAutomation(automation)).toBe(true);+ });});describe("resolveResponderDeploymentOption", () => {diff --git a/package-lock.json b/package-lock.jsonindex 53a0a88268..4d1609cd8e 100644--- a/package-lock.json+++ b/package-lock.json@@ -12,7 +12,7 @@"@heroui/react": "2.8.10","@microlink/react-json-view": "1.31.20","@monaco-editor/react": "4.7.0",- "@openhands/extensions": "0.11.0",+ "@openhands/extensions": "0.12.0","@openhands/typescript-client": "1.36.1","@react-router/node": "7.17.0","@react-router/serve": "7.17.0",@@ -4167,9 +4167,9 @@"license": "MIT"},"node_modules/@openhands/extensions": {- "version": "0.11.0",- "resolved": "https://registry.npmjs.org/@openhands/extensions/-/extensions-0.11.0.tgz",- "integrity": "sha512-xAQfAROOh3XnzOKIXiJcYNypEk36kPJhs8+xs8YgzsOCg5Wg4A6CPs2pR5CsLZ0MG+cxZEf5wTWdPn4+/g0w7g==",+ "version": "0.12.0",+ "resolved": "https://registry.npmjs.org/@openhands/extensions/-/extensions-0.12.0.tgz",+ "integrity": "sha512-S7s4hWcvrOfxUT4PMv/Sz5zRNh1tZEF5wQoWo/4TQKJFIgzy9trQJ0xz9UOZFgf4nh0juJEM2jwG9HMo8pmYfA==","license": "MIT","engines": {"node": ">=18.20.0"diff --git a/package.json b/package.jsonindex eb4fea44a8..3e1d797f11 100644--- a/package.json+++ b/package.json@@ -23,7 +23,7 @@"@heroui/react": "2.8.10","@microlink/react-json-view": "1.31.20","@monaco-editor/react": "4.7.0",- "@openhands/extensions": "0.11.0",+ "@openhands/extensions": "0.12.0","@openhands/typescript-client": "1.36.1","@react-router/node": "7.17.0","@react-router/serve": "7.17.0",diff --git a/scripts/check-translation-completeness.cjs b/scripts/check-translation-completeness.cjsindex c773d3eac7..0aa5bebf35 100755--- a/scripts/check-translation-completeness.cjs+++ b/scripts/check-translation-completeness.cjs@@ -53,6 +53,7 @@ const IDENTICAL_VALUE_ALLOWLIST = new Set(['SETTINGS$SKILLS_VERSION','SETTINGS$SLACK','SETTINGS$TITLE_GENERATION_PROFILE_OPTION',+ 'SETUP$REPOSITORY_PLACEHOLDER','VSCODE$TITLE','WORKSPACE$JUPYTER_TAB_LABEL',]);diff --git a/src/api/automation-service/automation-service.api.ts b/src/api/automation-service/automation-service.api.tsindex c58a7d8d71..10fc5073a4 100644--- a/src/api/automation-service/automation-service.api.ts+++ b/src/api/automation-service/automation-service.api.ts@@ -14,6 +14,12 @@ import type {AutomationsResponse,AutomationRunsResponse,} from "#/types/automation";+import { AUTOMATION_CREATE_ENDPOINT } from "#/manifests/automation-setup";+import type {+ DeploymentCapabilities,+ SetupRequestBody,+ ValidateDraftResponse,+} from "#/manifests/types";import type { Backend, ResolvedActiveBackend } from "../backend-registry/types";import {getActiveBackend,@@ -483,6 +489,86 @@ class AutomationService {URL.revokeObjectURL(url);}+ /**+ * Ask what this deployment supports, before a setup form renders.+ *+ * The setup endpoints answer a contract authored in `OpenHands/extensions`,+ * so their bodies are camelCase where the rest of this service is snake_case.+ */+ static async getCapabilities(): Promise<DeploymentCapabilities> {+ const active = getActiveBackend().backend;+ const path = `${AUTOMATION_BASE_PATH}/v1/capabilities`;++ if (active.kind === "cloud") {+ return callCloudProxy<DeploymentCapabilities>({+ backend: active,+ method: "GET",+ path,+ headers: await buildAutomationRequestHeaders(),+ });+ }++ const { data } =+ await localAutomationAxios.get<DeploymentCapabilities>(path);+ return data;+ }++ /**+ * Validate a draft without creating it. An invalid draft is a 200 carrying+ * field-addressed errors; only a malformed envelope is a 4xx.+ */+ static async validateDraft(+ body: SetupRequestBody,+ ): Promise<ValidateDraftResponse> {+ const active = getActiveBackend().backend;+ const path = `${AUTOMATION_BASE_PATH}/v1/validate`;++ if (active.kind === "cloud") {+ return callCloudProxy<ValidateDraftResponse>({+ backend: active,+ method: "POST",+ path,+ body,+ headers: await buildAutomationRequestHeaders(),+ });+ }++ const { data } = await localAutomationAxios.post<ValidateDraftResponse>(+ path,+ body,+ );+ return data;+ }++ /**+ * Create from a draft a setup form derived. Unlike {@link+ * AutomationService.createAutomation}, which exists for import and has to+ * park the record on a placeholder trigger, this sends the finished record in+ * one request.+ */+ static async createAutomationDraft(+ body: SetupRequestBody,+ ): Promise<Record<string, unknown>> {+ const active = getActiveBackend().backend;+ const path = `${AUTOMATION_BASE_PATH}${AUTOMATION_CREATE_ENDPOINT}`;++ if (active.kind === "cloud") {+ return callCloudProxy<Record<string, unknown>>({+ backend: active,+ method: "POST",+ path,+ body,+ headers: await buildAutomationRequestHeaders(),+ });+ }++ const { data } = await localAutomationAxios.post<Record<string, unknown>>(+ path,+ body,+ );+ return data;+ }+static async checkHealth(): Promise<AutomationHealthResponse> {const active = getActiveBackend().backend;const path = `${AUTOMATION_BASE_PATH}/health`;diff --git a/src/components/features/automations/recommended-automations-launcher.tsx b/src/components/features/automations/recommended-automations-launcher.tsxindex 2489e865d7..ccfa48da4a 100644--- a/src/components/features/automations/recommended-automations-launcher.tsx+++ b/src/components/features/automations/recommended-automations-launcher.tsx@@ -23,6 +23,11 @@ import {} from "#/utils/mcp-marketplace-utils";import { InstallServerModal } from "#/components/features/mcp-page/install-server-modal";import { useTracking } from "#/hooks/use-tracking";+import { SETUP_REGISTRY } from "#/manifests/manifest-sources";+import {+ getAutomationLaunchPrompt,+ getRequiredIntegrationIds,+} from "#/utils/automation-catalog";import { isResponderAutomation } from "#/utils/responder-deployment";import { RecommendedAutomationsSection } from "./recommended-automations-section";import { ResponderDeploymentModal } from "./responder-deployment-modal";@@ -34,23 +39,18 @@ interface RecommendedAutomationsLauncherProps {scrollableGrid?: boolean;}+/**+ * The marketplace entries a launch waits on. An integration the automation is+ * willing to start without is deliberately absent, so it never queues an+ * install modal the user has to dismiss.+ */function getRequiredEntries(automation: RecommendedAutomation) {const mcpMarketplace = getMcpMarketplaceCatalog(MCP_MARKETPLACE);- return automation.requiredIntegrationIds+ return getRequiredIntegrationIds(automation).map((id) => getMarketplaceEntryById(id, mcpMarketplace)).filter((entry): entry is MarketplaceEntry => !!entry);}-/**- * The catalog prompt (or slash command) is passed through as-is.- * API routing (host, auth) is discovered by the agent at runtime from- * `<RUNTIME_SERVICES>` in the system prompt — the skills themselves- * contain the instructions for reading that block.- */-export function buildAutomationPrompt(basePrompt: string): string {- return basePrompt;-}-export function RecommendedAutomationsLauncher({query,onLaunched,@@ -94,7 +94,16 @@ export function RecommendedAutomationsLauncher({}launchInFlightRef.current = true;- const prompt = buildAutomationPrompt(automation.prompt);+ // An automation that ships a setup experience is configured from its own+ // form, so the answers are collected before anything is created. The rest+ // still hand a slash command to an agent to interpret.+ if (SETUP_REGISTRY.findById(automation.id)) {+ navigate?.(`/automations/new/${automation.id}`);+ onLaunched?.();+ return;+ }++ const prompt = getAutomationLaunchPrompt(automation);createConversation.mutate({},diff --git a/src/components/features/automations/recommended-automations-section.tsx b/src/components/features/automations/recommended-automations-section.tsxindex 1e1ceaa95a..b202131a2e 100644--- a/src/components/features/automations/recommended-automations-section.tsx+++ b/src/components/features/automations/recommended-automations-section.tsx@@ -22,6 +22,10 @@ import {getMarketplaceEntryById,getMcpMarketplaceCatalog,} from "#/utils/mcp-marketplace-utils";+import {+ getAutomationLaunchPrompt,+ getIntegrationIds,+} from "#/utils/automation-catalog";import { cn } from "#/utils/utils";import {extensionModuleCardInteractiveClassName,@@ -70,9 +74,14 @@ function isProvenAutomation(automation: RecommendedAutomation): boolean {return (PROVEN_AUTOMATION_IDS as readonly string[]).includes(automation.id);}-function getRequiredEntries(automation: RecommendedAutomation) {+/**+ * Every integration the automation declares, including the ones it is willing+ * to start without: the card describes what the automation uses, so an+ * optional integration still belongs on it.+ */+function getIntegrationEntries(automation: RecommendedAutomation) {const mcpMarketplace = getMcpMarketplaceCatalog(MCP_MARKETPLACE);- return automation.requiredIntegrationIds+ return getIntegrationIds(automation).map((id) => getMarketplaceEntryById(id, mcpMarketplace)).filter((entry): entry is MarketplaceEntry => !!entry);}@@ -88,7 +97,7 @@ function automationMatchesQuery(automation.name,automation.category,automation.description,- automation.prompt,+ getAutomationLaunchPrompt(automation),...entries.map((entry) => entry.name),...entries.flatMap((entry) => entry.keywords ?? []),]@@ -98,24 +107,24 @@ function automationMatchesQuery(}/**- * Returns true only when at least one of the automation's required integration- * IDs resolves to a known marketplace entry. An empty result means none of- * the required integrations are in our catalog (or the array itself is empty),+ * Returns true only when at least one of the automation's integration IDs+ * resolves to a known marketplace entry. An empty result means none of the+ * automation's integrations are in our catalog (or it declares none at all),* so there is nothing for the user to set up — hide the card.* NOTE: intentionally no local/cloud backend availability filter; every entry* with a catalog match is shown regardless of runtimeAvailability.*/function isAutomationAvailable(automation: RecommendedAutomation) {- return getRequiredEntries(automation).length > 0;+ return getIntegrationEntries(automation).length > 0;}function buildRecommendedAutomationPills(- requiredEntries: MarketplaceEntry[],+ integrationEntries: MarketplaceEntry[],installedServers: MCPServerConfig[],missingCount: number,translate: TFunction,): SkillCardPill[] {- const pills: SkillCardPill[] = requiredEntries.map((entry) => {+ const pills: SkillCardPill[] = integrationEntries.map((entry) => {const installed = !!findInstalledEntryMatch(entry, installedServers);return {@@ -166,8 +175,8 @@ function AutomationCardGrid({return (<div className={cn("mt-3", extensionModuleCardGridClassName)}>{automations.map((automation) => {- const requiredEntries = getRequiredEntries(automation);- const missingCount = requiredEntries.filter(+ const integrationEntries = getIntegrationEntries(automation);+ const missingCount = integrationEntries.filter((entry) => !findInstalledEntryMatch(entry, installedServers),).length;@@ -184,7 +193,7 @@ function AutomationCardGrid({><div className="flex min-w-0 flex-1 items-start gap-3"><McpLogoStackBadge- entries={requiredEntries}+ entries={integrationEntries}testId={`recommended-automation-icon-${automation.id}`}/><div className="flex min-w-0 flex-1 flex-col gap-3">@@ -207,7 +216,7 @@ function AutomationCardGrid({<SkillCardPillRowpills={buildRecommendedAutomationPills(- requiredEntries,+ integrationEntries,installedServers,missingCount,translate,@@ -233,10 +242,10 @@ export function RecommendedAutomationsSection({const { t } = useTranslation("openhands");const visibleAutomations = RECOMMENDED_AUTOMATIONS.filter((automation) => {- const requiredEntries = getRequiredEntries(automation);+ const integrationEntries = getIntegrationEntries(automation);return (isAutomationAvailable(automation) &&- automationMatchesQuery(automation, requiredEntries, query)+ automationMatchesQuery(automation, integrationEntries, query));});diff --git a/src/components/features/manifest/manifest-form-field.tsx b/src/components/features/manifest/manifest-form-field.tsxnew file mode 100644index 0000000000..14a37c0476--- /dev/null+++ b/src/components/features/manifest/manifest-form-field.tsx@@ -0,0 +1,205 @@+import { useTranslation } from "react-i18next";+import { SettingsInput } from "#/components/features/settings/settings-input";+import { SettingsDropdownInput } from "#/components/features/settings/settings-dropdown-input";+import { GitRepoDropdown } from "#/components/features/home/git-repo-dropdown";+import { useActiveBackend } from "#/contexts/active-backend-context";+import { I18nKey } from "#/i18n/declaration";+import { formControlMultilineFieldClassName } from "#/utils/form-control-classes";+import { cn } from "#/utils/utils";+import type { GitRepository } from "#/types/git";+import type {+ SetupFieldOption,+ SetupFormField as SetupFormFieldDefinition,+} from "#/manifests/types";++export interface SetupFormFieldProps {+ /** The record key the field is declared under, and what `{{form.x}}` reads. */+ name: string;+ field: SetupFormFieldDefinition;+ value: string;+ /** Already-resolved copy: local checks and service errors look the same here. */+ error?: string;+ /** Declared options, or the ones the deployment supplied. */+ options: SetupFieldOption[];+ /** The picked repository, kept so the picker can show what is selected. */+ repository: GitRepository | null;+ disabled: boolean;+ onChange: (value: string) => void;+ onRepositoryChange: (repository: GitRepository | null) => void;+ onBlur: () => void;+}++/**+ * Render one manifest-declared field.+ *+ * The host knows how to render a field *type*; what any field means is the+ * manifest's business. Every field's own copy comes from the manifest and is+ * never translated by the host; the only host string is the format hint the+ * repository fallback below needs, because no manifest declares it.+ */+export function SetupFormField({+ name,+ field,+ value,+ error,+ options,+ repository,+ disabled,+ onChange,+ onRepositoryChange,+ onBlur,+}: SetupFormFieldProps) {+ const { t } = useTranslation("openhands");+ const { backend } = useActiveBackend();+ const testId = `setup-field-${name}`;+ const help = <p className="text-xs text-[var(--oh-muted)]">{field.help}</p>;++ // Listing a user's repositories is a cloud-backend capability: `GitService`+ // answers with an empty page on any other backend, so the picker would offer+ // a source that can never respond. Recommended automations are themselves+ // local-only, which makes that the common case rather than the edge one.+ const canListRepositories = backend.kind === "cloud";++ if (field.type === "repo-picker" && canListRepositories) {+ return (+ <div className="flex w-full flex-col gap-2.5">+ <FieldLabel field={field} />+ <GitRepoDropdown+ provider={field.provider ?? "github"}+ value={repository?.id ?? null}+ repositoryName={repository?.full_name ?? value ?? null}+ placeholder={field.placeholder}+ disabled={disabled}+ onChange={(selected) => {+ onRepositoryChange(selected ?? null);+ onChange(selected?.full_name ?? "");+ onBlur();+ }}+ />+ <FieldError testId={testId} error={error} />+ {help}+ </div>+ );+ }++ // A timezone field declares no options of its own: the accepted zones are the+ // deployment's, so it renders as a list once they are known and as a plain+ // input when they are not.+ if (+ field.type === "select" ||+ (field.type === "timezone" && options.length > 0)+ ) {+ return (+ <div className="flex w-full flex-col gap-2.5">+ <SettingsDropdownInput+ testId={testId}+ name={name}+ label={<FieldLabelText field={field} />}+ items={options.map((option) => ({+ key: option.value,+ label: option.label,+ }))}+ selectedKey={value || undefined}+ placeholder={field.placeholder}+ isDisabled={disabled}+ required={field.required}+ onSelectionChange={(key) => {+ onChange(key === null ? "" : String(key));+ onBlur();+ }}+ />+ <FieldError testId={testId} error={error} />+ {help}+ </div>+ );+ }++ if (field.type === "textarea") {+ return (+ <label className="flex w-full flex-col gap-2.5">+ <FieldLabelText field={field} />+ <textarea+ data-testid={testId}+ name={name}+ rows={4}+ value={value}+ placeholder={field.placeholder}+ disabled={disabled}+ aria-invalid={!!error}+ onChange={(event) => onChange(event.target.value)}+ onBlur={onBlur}+ className={cn(+ formControlMultilineFieldClassName,+ error && "border-red-500",+ )}+ />+ <FieldError testId={testId} error={error} />+ {help}+ </label>+ );+ }++ // `text`, `cron`, an unresolved `timezone` and a repository that cannot be+ // browsed are all single-line strings to the host; only the manifest and the+ // service know what a cron expression or a repository name means. A manifest+ // states the format of everything it declares except the repository, whose+ // shape the host derives, so that one hint is host copy.+ const placeholder =+ field.placeholder ??+ (field.type === "repo-picker"+ ? t(I18nKey.SETUP$REPOSITORY_PLACEHOLDER)+ : undefined);++ return (+ <div className="flex w-full flex-col gap-2.5">+ <SettingsInput+ testId={testId}+ name={name}+ type="text"+ label={field.label}+ value={value}+ placeholder={placeholder}+ isDisabled={disabled}+ showRequiredTag={field.required}+ error={error}+ onChange={onChange}+ onBlur={onBlur}+ />+ {help}+ </div>+ );+}++function FieldLabelText({ field }: { field: SetupFormFieldDefinition }) {+ return (+ <span className="flex items-center gap-2 text-sm">+ {field.label}+ {field.required && (+ <span className="text-sm leading-none text-red-400" aria-hidden>+ *+ </span>+ )}+ </span>+ );+}++function FieldLabel({ field }: { field: SetupFormFieldDefinition }) {+ return (+ <div className="flex items-center gap-2">+ <FieldLabelText field={field} />+ </div>+ );+}++function FieldError({ testId, error }: { testId: string; error?: string }) {+ if (!error) return null;+ return (+ <p+ role="alert"+ data-testid={`${testId}-error`}+ className="-mt-1 text-xs text-red-400"+ >+ {error}+ </p>+ );+}diff --git a/src/components/features/manifest/manifest-prerequisites-step.tsx b/src/components/features/manifest/manifest-prerequisites-step.tsxnew file mode 100644index 0000000000..c6f95bb020--- /dev/null+++ b/src/components/features/manifest/manifest-prerequisites-step.tsx@@ -0,0 +1,43 @@+import { useTranslation } from "react-i18next";+import { I18nKey } from "#/i18n/declaration";+import { NavigationLink } from "#/components/shared/navigation-link";+import type { SetupPrerequisitesResult } from "#/hooks/query/use-manifest-prerequisites";++/** Where the user goes to connect an integration. */+const INTEGRATIONS_PATH = "/mcp";++export interface SetupPrerequisitesStepProps {+ prerequisites: SetupPrerequisitesResult;+}++/**+ * Stage 3 — what has to be connected before the form is worth filling in.+ *+ * Each integration is listed with the reason the manifest gives for needing it,+ * so the user is told why rather than just what.+ */+export function SetupPrerequisitesStep({+ prerequisites,+}: SetupPrerequisitesStepProps) {+ const { t } = useTranslation("openhands");+ const { blockingIntegrations, warningIntegrations } = prerequisites;++ return (+ <div className="flex flex-col gap-4" data-testid="setup-prerequisites">+ {[...blockingIntegrations, ...warningIntegrations].map(+ ({ id, requirement, entry }) => (+ <div key={id} className="flex flex-col gap-1">+ <span className="text-sm">{entry?.name ?? id}</span>+ <span className="text-xs text-[var(--oh-muted)]">+ {requirement.message}+ </span>+ </div>+ ),+ )}++ <NavigationLink to={INTEGRATIONS_PATH} className="text-sm underline">+ {t(I18nKey.SETUP$MANAGE_INTEGRATIONS)}+ </NavigationLink>+ </div>+ );+}diff --git a/src/components/features/manifest/manifest-review-step.tsx b/src/components/features/manifest/manifest-review-step.tsxnew file mode 100644index 0000000000..f9b7a1ba54--- /dev/null+++ b/src/components/features/manifest/manifest-review-step.tsx@@ -0,0 +1,36 @@+import { useTranslation } from "react-i18next";+import { I18nKey } from "#/i18n/declaration";+import { collectFields } from "#/manifests/manifest-local-validation";+import type { SetupBlock, SetupFormValues } from "#/manifests/types";++export interface SetupReviewStepProps {+ setup: SetupBlock;+ values: SetupFormValues;+}++/**+ * Stage 7 — the plain-language summary the user confirms.+ *+ * The last cheap moment to catch a wrong answer, and the last point at which+ * nothing has been created yet. A manifest declares no summary of its own: one+ * row per declared field, labelled the way the field was labelled, says the+ * same thing without asking every entry to restate it.+ */+export function SetupReviewStep({ setup, values }: SetupReviewStepProps) {+ const { t } = useTranslation("openhands");++ return (+ <div className="flex flex-col gap-4" data-testid="setup-review">+ <dl className="flex flex-col gap-3">+ {Object.entries(collectFields(setup)).map(([name, field]) => (+ <div key={name} className="flex flex-col gap-0.5">+ <dt className="text-xs text-[var(--oh-muted)]">{field.label}</dt>+ <dd className="text-sm break-words">+ {(values[name] ?? "").trim() || t(I18nKey.SETUP$EMPTY_VALUE)}+ </dd>+ </div>+ ))}+ </dl>+ </div>+ );+}diff --git a/src/components/features/manifest/manifest-setup-dialog.tsx b/src/components/features/manifest/manifest-setup-dialog.tsxnew file mode 100644index 0000000000..f300c79cbb--- /dev/null+++ b/src/components/features/manifest/manifest-setup-dialog.tsx@@ -0,0 +1,397 @@+import { useEffect, useMemo, useRef, useState } from "react";+import { useTranslation } from "react-i18next";+import { useNavigate } from "react-router";+import { ModalBackdrop } from "#/components/shared/modals/modal-backdrop";+import { ModalCloseButton } from "#/components/shared/modals/modal-close-button";+import { BrandButton } from "#/components/features/settings/brand-button";+import { LoadingSpinner } from "#/components/shared/loading-spinner";+import { I18nKey } from "#/i18n/declaration";+import { cn } from "#/utils/utils";+import { modalTitleLgClassName } from "#/utils/modal-classes";+import { getApiErrorBody } from "#/utils/api-error-message";+import { useTracking } from "#/hooks/use-tracking";+import { useSetupCapabilities } from "#/hooks/query/use-manifest-capabilities";+import { useSetupPrerequisites } from "#/hooks/query/use-manifest-prerequisites";+import { useSetupPreflight } from "#/hooks/use-manifest-preflight";+import { useSetupAction } from "#/manifests/manifest-actions";+import {+ buildCreatePayload,+ deriveErrorMap,+} from "#/manifests/automation-setup";+import {+ collectFields,+ getFieldOptions,+ getInitialFormValues,+ resolveFieldOverrides,+ validateFormValues,+ type SetupFieldError,+ type SetupFieldErrors,+} from "#/manifests/manifest-local-validation";+import {+ mapServiceErrors,+ normalizeServiceErrors,+ type MappedManifestErrors,+} from "#/manifests/manifest-error-map";+import type { GitRepository } from "#/types/git";+import type { SetupEntry, SetupFormValues } from "#/manifests/types";+import { SetupFormField } from "./manifest-form-field";+import { SetupPrerequisitesStep } from "./manifest-prerequisites-step";+import { SetupReviewStep } from "./manifest-review-step";++type SetupStep = "prerequisites" | "form" | "review";++/** How long a field rests after a blur before the draft is sent for checking. */+const PREFLIGHT_DEBOUNCE_MS = 400;++const NO_SERVICE_ERRORS: MappedManifestErrors = {+ fieldErrors: {},+ formErrors: [],+};++function hasAnyError(errors: MappedManifestErrors): boolean {+ return (+ errors.formErrors.length > 0 || Object.keys(errors.fieldErrors).length > 0+ );+}++/** Where a completed setup lands: the new automation, or the conversation. */+function getDestination(response: Record<string, unknown>): string | null {+ if (typeof response.conversation_id === "string") {+ return `/conversations/${response.conversation_id}`;+ }+ if (typeof response.id === "string") return `/automations/${response.id}`;+ return null;+}++export interface SetupDialogProps {+ entry: SetupEntry;+ onClose: () => void;+}++/**+ * The setup host: capabilities check, prerequisites, form, review, and the+ * action the manifest's mode selects, rendered as a dialog.+ *+ * The host runs the stages and owns everything the same for every entry; the+ * manifest supplies only what varies. Any string the user reads here is either+ * manifest-authored or host chrome.+ */+export function SetupDialog({ entry, onClose }: SetupDialogProps) {+ const { t } = useTranslation("openhands");+ const navigate = useNavigate();++ const capabilities = useSetupCapabilities(entry);+ const prerequisites = useSetupPrerequisites(entry);+ const runPreflight = useSetupPreflight(entry);+ const runAction = useSetupAction();+ const {+ trackAutomationSetupOpened,+ trackAutomationSetupValidated,+ trackAutomationSetupCreated,+ trackAutomationSetupFailed,+ } = useTracking();++ const [step, setStep] = useState<SetupStep>("prerequisites");+ const [values, setValues] = useState<SetupFormValues>(() =>+ getInitialFormValues(entry.setup),+ );+ const [repositories, setRepositories] = useState<+ Record<string, GitRepository | null>+ >({});+ const [localErrors, setLocalErrors] = useState<SetupFieldErrors>({});+ const [serviceErrors, setServiceErrors] =+ useState<MappedManifestErrors>(NO_SERVICE_ERRORS);+ const [isSubmitting, setIsSubmitting] = useState(false);++ // Blur-triggered preflight reads the values as they are when the field is+ // left, which can be the same tick as the change that caused it.+ const valuesRef = useRef(values);+ const blurTimerRef = useRef<number | null>(null);+ useEffect(+ () => () => {+ if (blurTimerRef.current) window.clearTimeout(blurTimerRef.current);+ },+ [],+ );++ const fields = useMemo(() => collectFields(entry.setup), [entry]);+ const overrides = useMemo(+ () => resolveFieldOverrides(entry.setup, capabilities.capabilities),+ [entry, capabilities.capabilities],+ );+ const payload = useMemo(+ () => buildCreatePayload(entry, values),+ [entry, values],+ );+ const errorMap = useMemo(() => deriveErrorMap(entry), [entry]);++ const emittedOpenRef = useRef(false);+ useEffect(() => {+ if (emittedOpenRef.current) return;+ emittedOpenRef.current = true;+ trackAutomationSetupOpened({ automationId: entry.id });+ }, [entry.id, trackAutomationSetupOpened]);++ const isUnsupported = capabilities.supported === false;+ const showPrerequisites =+ prerequisites.blockingIntegrations.length > 0 ||+ prerequisites.warningIntegrations.length > 0;+ // Prerequisites resolve asynchronously; deriving the step keeps an entry with+ // nothing to check from flashing an empty first screen.+ const currentStep: SetupStep =+ step === "prerequisites" && !showPrerequisites ? "form" : step;++ const setFieldValue = (name: string, value: string) => {+ valuesRef.current = { ...valuesRef.current, [name]: value };+ setValues(valuesRef.current);+ setLocalErrors(({ [name]: _removed, ...rest }) => rest);+ setServiceErrors((current) => {+ if (!(name in current.fieldErrors)) return current;+ const { [name]: _cleared, ...fieldErrors } = current.fieldErrors;+ return { ...current, fieldErrors };+ });+ };++ const handleFieldBlur = () => {+ if (blurTimerRef.current) window.clearTimeout(blurTimerRef.current);+ blurTimerRef.current = window.setTimeout(() => {+ void runPreflight(valuesRef.current).then((result) => {+ if (result) setServiceErrors(result);+ });+ }, PREFLIGHT_DEBOUNCE_MS);+ };++ const handleContinue = async () => {+ if (currentStep === "prerequisites") {+ setStep("form");+ return;+ }++ const failures = validateFormValues(entry.setup, values, overrides);+ if (Object.keys(failures).length > 0) {+ setLocalErrors(failures);+ return;+ }+ setLocalErrors({});++ const result = await runPreflight(values);+ if (result && hasAnyError(result)) {+ setServiceErrors(result);+ return;+ }++ setServiceErrors(NO_SERVICE_ERRORS);+ trackAutomationSetupValidated({ automationId: entry.id });+ setStep("review");+ };++ const handleConfirm = async () => {+ setIsSubmitting(true);+ try {+ const { response } = await runAction(entry, values, payload);+ trackAutomationSetupCreated({+ automationId: entry.id,+ setupMode: entry.setup.mode,+ });+ const destination = getDestination(response);+ if (destination) navigate(destination, { replace: true });+ else onClose();+ } catch (error) {+ trackAutomationSetupFailed({+ automationId: entry.id,+ setupMode: entry.setup.mode,+ });+ const mapped = mapServiceErrors(+ normalizeServiceErrors(getApiErrorBody(error), payload),+ errorMap,+ );+ setServiceErrors(+ hasAnyError(mapped)+ ? mapped+ : {+ fieldErrors: {},+ formErrors: [t(I18nKey.SETUP$SUBMIT_FAILED)],+ },+ );+ setStep("form");+ } finally {+ setIsSubmitting(false);+ }+ };++ const resolveFieldError = (name: string): string | undefined => {+ const local = localErrors[name];+ return local ? formatFieldError(local, t) : serviceErrors.fieldErrors[name];+ };++ const isLoading = capabilities.isLoading || prerequisites.isLoading;++ const title = (() => {+ if (isUnsupported) return t(I18nKey.SETUP$UNAVAILABLE_TITLE);+ if (currentStep === "prerequisites")+ return t(I18nKey.SETUP$PREREQUISITES_TITLE);+ if (currentStep === "review") return t(I18nKey.SETUP$REVIEW_TITLE);+ return entry.name;+ })();++ return (+ <ModalBackdrop onClose={onClose} aria-label={entry.name}>+ <div+ data-testid="setup-dialog"+ className="relative flex max-h-[85vh] w-[92vw] max-w-lg flex-col rounded-xl border border-[var(--oh-border)] bg-base-secondary"+ >+ <ModalCloseButton+ onClose={onClose}+ testId="setup-dialog-close"+ disabled={isSubmitting}+ />+ <header className="flex-shrink-0 px-6 pb-4 pt-6">+ <h2 className={cn("pr-6", modalTitleLgClassName)}>{title}</h2>+ </header>++ <div className="min-h-0 flex-1 overflow-y-auto px-6">+ {isLoading && (+ <div className="flex justify-center py-6">+ <LoadingSpinner size="small" />+ </div>+ )}++ {!isLoading && isUnsupported && (+ <div className="flex flex-col gap-2">+ <p className="text-sm text-[var(--oh-muted)]">+ {t(I18nKey.SETUP$UNSUPPORTED_MESSAGE)}+ </p>+ {/* The unmet requirements are the names both sides of the+ contract already use, so they are printed rather than+ translated. Without them the block is undiagnosable: the+ deployment answered, and the host would be discarding the+ one thing it learned. */}+ {capabilities.unmet.length > 0 && (+ <p+ data-testid="setup-unmet-requirements"+ className="text-sm text-[var(--oh-muted)]"+ >+ {capabilities.unmet.join(", ")}+ </p>+ )}+ </div>+ )}++ {!isLoading && !isUnsupported && currentStep === "prerequisites" && (+ <SetupPrerequisitesStep prerequisites={prerequisites} />+ )}++ {!isLoading && !isUnsupported && currentStep === "form" && (+ <div className="flex flex-col gap-5">+ <p className="text-sm text-[var(--oh-muted)]">+ {entry.description}+ </p>+ {entry.setup.form.note && (+ <p className="text-sm text-[var(--oh-muted)]">+ {entry.setup.form.note}+ </p>+ )}+ {Object.entries(fields).map(([name, field]) => (+ <SetupFormField+ key={name}+ name={name}+ field={field}+ value={values[name] ?? ""}+ error={resolveFieldError(name)}+ options={getFieldOptions(name, field, overrides)}+ repository={repositories[name] ?? null}+ disabled={isSubmitting}+ onChange={(value) => setFieldValue(name, value)}+ onRepositoryChange={(repository) =>+ setRepositories((current) => ({+ ...current,+ [name]: repository,+ }))+ }+ onBlur={handleFieldBlur}+ />+ ))}+ </div>+ )}++ {!isLoading && !isUnsupported && currentStep === "review" && (+ <SetupReviewStep setup={entry.setup} values={values} />+ )}++ {serviceErrors.formErrors.map((message) => (+ <p+ key={message}+ role="alert"+ data-testid="setup-form-error"+ className="pt-4 text-sm text-red-400"+ >+ {message}+ </p>+ ))}+ </div>++ <footer className="flex flex-shrink-0 justify-end gap-2 px-6 pb-6 pt-4">+ {currentStep === "review" && (+ <BrandButton+ testId="setup-back-button"+ type="button"+ variant="secondary"+ isDisabled={isSubmitting}+ onClick={() => setStep("form")}+ >+ {t(I18nKey.BUTTON$BACK)}+ </BrandButton>+ )}++ {isUnsupported ? (+ <BrandButton type="button" variant="secondary" onClick={onClose}>+ {t(I18nKey.BUTTON$CLOSE)}+ </BrandButton>+ ) : (+ <BrandButton+ testId="setup-continue-button"+ type="button"+ variant="primary"+ isDisabled={+ isLoading ||+ isSubmitting ||+ (currentStep === "prerequisites" && prerequisites.isBlocked)+ }+ onClick={+ currentStep === "review" ? handleConfirm : handleContinue+ }+ >+ {currentStep === "review"+ ? t(I18nKey.SETUP$CONFIRM)+ : t(I18nKey.BUTTON$CONTINUE)}+ </BrandButton>+ )}+ </footer>+ </div>+ </ModalBackdrop>+ );+}++function formatFieldError(+ error: SetupFieldError,+ t: (key: I18nKey, options?: Record<string, unknown>) => string,+): string {+ switch (error.code) {+ case "required":+ return t(I18nKey.SETUP$VALIDATION_REQUIRED);+ case "minLength":+ return t(I18nKey.SETUP$VALIDATION_MIN_LENGTH, { length: error.length });+ case "maxLength":+ return t(I18nKey.SETUP$VALIDATION_MAX_LENGTH, { length: error.length });+ case "invalidOption":+ return t(I18nKey.SETUP$VALIDATION_INVALID_OPTION);+ case "unsafeExpressionLiteral":+ return t(I18nKey.SETUP$VALIDATION_UNSAFE_VALUE);+ default: {+ // A code added to `SetupFieldError` without a message here is a compile+ // error rather than a field that silently reads "this field is required".+ const exhaustive: never = error;+ return exhaustive;+ }+ }+}diff --git a/src/components/features/onboarding/onboarding-modal.tsx b/src/components/features/onboarding/onboarding-modal.tsxindex 76e303b525..545e1dd583 100644--- a/src/components/features/onboarding/onboarding-modal.tsx+++ b/src/components/features/onboarding/onboarding-modal.tsx@@ -266,9 +266,10 @@ export function OnboardingModal({selectedAgentId,]);- // Onboarding Completed — `onLaunched` runs only after a conversation is- // successfully created (the hello message or a recommended automation), so- // wrapping it captures completion exactly once before the modal closes.+ // Onboarding Completed — `onLaunched` runs only once the user has committed+ // to a launch: a created conversation for the hello message or a recommended+ // automation, or the setup form for an automation that ships one. Wrapping it+ // captures completion exactly once before the modal closes.const handleCompleted = () => {trackOnboardingCompleted({ agent: selectedAgentId });onClose();diff --git a/src/hooks/query/query-keys.ts b/src/hooks/query/query-keys.tsindex 3a16375265..69e8bdb175 100644--- a/src/hooks/query/query-keys.ts+++ b/src/hooks/query/query-keys.ts@@ -50,6 +50,11 @@ export const PLUGINS_QUERY_KEYS = {local: ["plugins-local"] as const,} as const;+export const SETUP_QUERY_KEYS = {+ /** What the deployment supports. The same answer for every setup entry. */+ capabilities: () => ["setup-capabilities"] as const,+} as const;+export const APP_UPDATE_QUERY_KEYS = {/** Latest published @openhands/agent-canvas version (npm `latest` dist-tag). */latestVersion: ["agent-canvas-latest-version"] as const,diff --git a/src/hooks/query/use-manifest-capabilities.ts b/src/hooks/query/use-manifest-capabilities.tsnew file mode 100644index 0000000000..225cee6593--- /dev/null+++ b/src/hooks/query/use-manifest-capabilities.ts@@ -0,0 +1,71 @@+import { useQuery } from "@tanstack/react-query";+import AutomationService from "#/api/automation-service/automation-service.api";+import { useActiveBackend } from "#/contexts/active-backend-context";+import {+ assessCapabilityRequirements,+ type SetupCapabilitySupport,+} from "#/manifests/manifest-capabilities";+import type { DeploymentCapabilities, SetupEntry } from "#/manifests/types";+import { SETUP_QUERY_KEYS } from "./query-keys";++export interface SetupCapabilitiesResult {+ /** The discovery response, or null when there is nothing to report. */+ capabilities: DeploymentCapabilities | null;+ supported: SetupCapabilitySupport;+ /** Which requirements a `false` verdict came from; empty otherwise. */+ unmet: string[];+ isLoading: boolean;+}++/**+ * Ask the deployment what it supports, then compare that against what the+ * manifest requires.+ *+ * A deployment that does not answer resolves to "unknown" rather than+ * unsupported. Discovery is not implemented on every deployment yet, and+ * refusing to render on a failed probe would block every manifest on the ones+ * that simply cannot be asked. Nothing is resolved into the form in that case+ * either, so the manifest's own defaults stand.+ */+export function useSetupCapabilities(+ entry: SetupEntry,+): SetupCapabilitiesResult {+ const { backend, orgId } = useActiveBackend();++ const query = useQuery({+ queryKey: [...SETUP_QUERY_KEYS.capabilities(), backend.id, orgId],+ queryFn: () => AutomationService.getCapabilities(),+ retry: false,+ staleTime: 1000 * 60 * 5,+ // A deployment without discovery is an expected state, not a user-facing+ // failure.+ meta: { disableToast: true },+ });++ if (query.isLoading) {+ return {+ capabilities: null,+ supported: "unknown",+ unmet: [],+ isLoading: true,+ };+ }++ if (!query.data) {+ return {+ capabilities: null,+ supported: "unknown",+ unmet: [],+ isLoading: false,+ };+ }++ const assessment = assessCapabilityRequirements(entry, query.data);++ return {+ capabilities: query.data,+ supported: assessment.supported,+ unmet: assessment.unmet,+ isLoading: false,+ };+}diff --git a/src/hooks/query/use-manifest-prerequisites.ts b/src/hooks/query/use-manifest-prerequisites.tsnew file mode 100644index 0000000000..adbe5df1d4--- /dev/null+++ b/src/hooks/query/use-manifest-prerequisites.ts@@ -0,0 +1,82 @@+import { useMemo } from "react";+import {+ INTEGRATION_CATALOG as MCP_MARKETPLACE,+ type IntegrationCatalogEntry as MarketplaceEntry,+} from "@openhands/extensions/integrations";+import {+ findInstalledEntryMatch,+ getMarketplaceEntryById,+ getMcpMarketplaceCatalog,+} from "#/utils/mcp-marketplace-utils";+import { flattenMcpConfig } from "#/utils/mcp-installed-servers";+import { parseMcpConfig } from "#/utils/mcp-config";+import type {+ SetupEntry,+ SetupIntegrationRequirement,+} from "#/manifests/types";+import { useSettings } from "./use-settings";++export interface MissingSetupIntegration {+ id: string;+ requirement: SetupIntegrationRequirement;+ /** The catalog entry, when the id resolves to one. */+ entry: MarketplaceEntry | null;+}++export interface SetupPrerequisitesResult {+ /** Unconnected integrations the manifest declares as required. */+ blockingIntegrations: MissingSetupIntegration[];+ /** Unconnected integrations the manifest is willing to proceed without. */+ warningIntegrations: MissingSetupIntegration[];+ isBlocked: boolean;+ isLoading: boolean;+}++/**+ * Stage 3 — which of the accounts this manifest needs are already connected.+ *+ * A requirement is blocking unless it opts out with `required: false`, which is+ * the manifest's way of saying the integration can be connected later, during+ * setup itself.+ */+export function useSetupPrerequisites(+ entry: SetupEntry,+): SetupPrerequisitesResult {+ const integrations = entry.requires.integrations;+ const { data: settings, isLoading } = useSettings();++ const installedServers = useMemo(+ () =>+ flattenMcpConfig(parseMcpConfig(settings?.agent_settings?.mcp_config)),+ [settings?.agent_settings?.mcp_config],+ );++ const missingIntegrations = useMemo<MissingSetupIntegration[]>(() => {+ const catalog = getMcpMarketplaceCatalog(MCP_MARKETPLACE);+ return Object.entries(integrations)+ .map(([id, requirement]) => ({+ id,+ requirement,+ entry: getMarketplaceEntryById(id, catalog) ?? null,+ }))+ .filter(+ ({ entry: catalogEntry }) =>+ !catalogEntry ||+ !findInstalledEntryMatch(catalogEntry, installedServers),+ );+ }, [integrations, installedServers]);++ const blockingIntegrations = missingIntegrations.filter(+ ({ requirement }) => requirement.required !== false,+ );+ const warningIntegrations = missingIntegrations.filter(+ ({ requirement }) => requirement.required === false,+ );++ return {+ blockingIntegrations,+ warningIntegrations,+ isBlocked: blockingIntegrations.length > 0,+ isLoading,+ };+}diff --git a/src/hooks/use-manifest-preflight.ts b/src/hooks/use-manifest-preflight.tsnew file mode 100644index 0000000000..17afabf9f0--- /dev/null+++ b/src/hooks/use-manifest-preflight.ts@@ -0,0 +1,88 @@+import { useCallback, useMemo, useRef } from "react";+import axios from "axios";+import AutomationService from "#/api/automation-service/automation-service.api";+import { isSdkHttpStatusError } from "#/api/agent-server-compatibility";+import {+ mapServiceErrors,+ normalizeServiceErrors,+ type MappedManifestErrors,+} from "#/manifests/manifest-error-map";+import {+ buildPreflightBody,+ deriveErrorMap,+} from "#/manifests/automation-setup";+import type {+ SetupEntry,+ SetupFormValues,+ SetupRequestBody,+} from "#/manifests/types";++const NO_ERRORS: MappedManifestErrors = { fieldErrors: {}, formErrors: [] };++/** What a deployment that does not serve the validate endpoint answers with. */+const NOT_IMPLEMENTED_STATUSES = [404, 501];++/**+ * Whether a failed preflight means "this deployment does not implement it".+ * Local calls throw an `AxiosError` and cloud calls throw the shared client's+ * `HttpError`, so both shapes are read.+ */+function isPreflightUnimplemented(error: unknown): boolean {+ return NOT_IMPLEMENTED_STATUSES.some(+ (status) =>+ isSdkHttpStatusError(error, status) ||+ (axios.isAxiosError(error) && error.response?.status === status),+ );+}++/**+ * Stage 6 — ask the service whether a draft is valid before anything is created.+ *+ * The service is the authoritative validator, so what it receives is the derived+ * payload rather than the raw form values: what is checked is exactly what would+ * be sent. Errors come back addressed by payload path and are translated back to+ * fields through the map derived from that same builder.+ *+ * Resolves to null when there is no verdict — the entry has no draft to check,+ * the deployment does not implement preflight, a newer run has already+ * superseded this one, or the request failed. A missing preflight is not a+ * failure: local checks and the create response still stand between the user+ * and a bad configuration. Only a deployment without the endpoint is an+ * expected failure though, so any other one is reported.+ */+export function useSetupPreflight(entry: SetupEntry) {+ const latestRequestRef = useRef(0);+ const errorMap = useMemo(() => deriveErrorMap(entry), [entry]);++ return useCallback(+ async (+ formValues: SetupFormValues,+ ): Promise<MappedManifestErrors | null> => {+ const body = buildPreflightBody(entry, formValues);+ if (!body) return null;++ latestRequestRef.current += 1;+ const requestId = latestRequestRef.current;++ try {+ const result = await AutomationService.validateDraft(body);+ if (requestId !== latestRequestRef.current) return null;+ if (result?.valid) return NO_ERRORS;++ return mapServiceErrors(+ normalizeServiceErrors(result, body.draft as SetupRequestBody),+ errorMap,+ );+ } catch (error) {+ // A broken validator and an unimplemented one degrade to the same+ // advisory "no verdict", so the only thing that separates them is this+ // line. Without it a service returning 500 on every draft is invisible.+ if (!isPreflightUnimplemented(error)) {+ console.warn("Automation setup preflight failed:", error);+ }+ return null;+ }+ },+ [entry, errorMap],+ );+}diff --git a/src/hooks/use-tracking.ts b/src/hooks/use-tracking.tsindex a5fdf4fb86..6d6b30d2e0 100644--- a/src/hooks/use-tracking.ts+++ b/src/hooks/use-tracking.ts@@ -131,6 +131,54 @@ export const useTracking = () => {});};+ /**+ * The setup funnel: opened → validated → created, or failed.+ *+ * A manifest declares no analytics of its own, so the stages are the same for+ * every entry and only the id it carries varies.+ */+ const trackAutomationSetupOpened = ({+ automationId,+ }: {+ automationId: string;+ }) => {+ track("automation_setup_opened", { automation_id: automationId });+ };++ const trackAutomationSetupValidated = ({+ automationId,+ }: {+ automationId: string;+ }) => {+ track("automation_setup_validated", { automation_id: automationId });+ };++ const trackAutomationSetupCreated = ({+ automationId,+ setupMode,+ }: {+ automationId: string;+ setupMode: string;+ }) => {+ track("automation_setup_created", {+ automation_id: automationId,+ setup_mode: setupMode,+ });+ };++ const trackAutomationSetupFailed = ({+ automationId,+ setupMode,+ }: {+ automationId: string;+ setupMode: string;+ }) => {+ track("automation_setup_failed", {+ automation_id: automationId,+ setup_mode: setupMode,+ });+ };+const trackInitialQuerySubmitted = ({entryPoint,queryCharacterLength,@@ -342,6 +390,10 @@ export const useTracking = () => {trackCreatePrButtonClick,trackUserSignupCompleted,trackPrebuiltAutomationEnabled,+ trackAutomationSetupOpened,+ trackAutomationSetupValidated,+ trackAutomationSetupCreated,+ trackAutomationSetupFailed,trackInitialQuerySubmitted,trackUserMessageSent,trackDownloadVsCodeButtonClicked,diff --git a/src/i18n/translation.json b/src/i18n/translation.jsonindex f27e27ec22..d81aec7a69 100644--- a/src/i18n/translation.json+++ b/src/i18n/translation.json@@ -35358,5 +35358,260 @@"de": "Versionshinweise anzeigen","uk": "Переглянути примітки до випуску","ca": "Mostra les notes de la versió"+ },+ "BUTTON$CONTINUE": {+ "en": "Continue",+ "ja": "続ける",+ "zh-CN": "继续",+ "zh-TW": "繼續",+ "ko-KR": "계속",+ "no": "Fortsett",+ "it": "Continua",+ "pt": "Continuar",+ "es": "Continuar",+ "ar": "متابعة",+ "fr": "Continuer",+ "tr": "Devam et",+ "de": "Weiter",+ "uk": "Продовжити",+ "ca": "Continua"+ },+ "SETUP$PREREQUISITES_TITLE": {+ "en": "Before you start",+ "ja": "開始する前に",+ "zh-CN": "开始之前",+ "zh-TW": "開始之前",+ "ko-KR": "시작하기 전에",+ "no": "Før du starter",+ "it": "Prima di iniziare",+ "pt": "Antes de começar",+ "es": "Antes de empezar",+ "ar": "قبل البدء",+ "fr": "Avant de commencer",+ "tr": "Başlamadan önce",+ "de": "Bevor Sie beginnen",+ "uk": "Перш ніж почати",+ "ca": "Abans de començar"+ },+ "SETUP$MANAGE_INTEGRATIONS": {+ "en": "Manage integrations",+ "ja": "連携を管理",+ "zh-CN": "管理集成",+ "zh-TW": "管理整合",+ "ko-KR": "연동 관리",+ "no": "Administrer integrasjoner",+ "it": "Gestisci integrazioni",+ "pt": "Gerir integrações",+ "es": "Gestionar integraciones",+ "ar": "إدارة عمليات التكامل",+ "fr": "Gérer les intégrations",+ "tr": "Entegrasyonları yönet",+ "de": "Integrationen verwalten",+ "uk": "Керувати інтеграціями",+ "ca": "Gestiona les integracions"+ },+ "SETUP$UNAVAILABLE_TITLE": {+ "en": "Not available",+ "ja": "利用できません",+ "zh-CN": "不可用",+ "zh-TW": "無法使用",+ "ko-KR": "사용할 수 없음",+ "no": "Ikke tilgjengelig",+ "it": "Non disponibile",+ "pt": "Indisponível",+ "es": "No disponible",+ "ar": "غير متاح",+ "fr": "Non disponible",+ "tr": "Kullanılamıyor",+ "de": "Nicht verfügbar",+ "uk": "Недоступно",+ "ca": "No disponible"+ },+ "SETUP$SUBMIT_FAILED": {+ "en": "Something went wrong. Nothing was created.",+ "ja": "エラーが発生しました。何も作成されていません。",+ "zh-CN": "出现问题。未创建任何内容。",+ "zh-TW": "發生問題。未建立任何項目。",+ "ko-KR": "문제가 발생했습니다. 아무것도 생성되지 않았습니다.",+ "no": "Noe gikk galt. Ingenting ble opprettet.",+ "it": "Si è verificato un problema. Non è stato creato nulla.",+ "pt": "Algo correu mal. Nada foi criado.",+ "es": "Algo ha fallado. No se ha creado nada.",+ "ar": "حدث خطأ ما. لم يتم إنشاء أي شيء.",+ "fr": "Une erreur s'est produite. Rien n'a été créé.",+ "tr": "Bir sorun oluştu. Hiçbir şey oluşturulmadı.",+ "de": "Etwas ist schiefgelaufen. Es wurde nichts erstellt.",+ "uk": "Щось пішло не так. Нічого не створено.",+ "ca": "Alguna cosa ha anat malament. No s'ha creat res."+ },+ "SETUP$VALIDATION_REQUIRED": {+ "en": "This field is required.",+ "ja": "このフィールドは必須です。",+ "zh-CN": "此字段为必填项。",+ "zh-TW": "此欄位為必填。",+ "ko-KR": "필수 항목입니다.",+ "no": "Dette feltet er påkrevd.",+ "it": "Questo campo è obbligatorio.",+ "pt": "Este campo é obrigatório.",+ "es": "Este campo es obligatorio.",+ "ar": "هذا الحقل مطلوب.",+ "fr": "Ce champ est obligatoire.",+ "tr": "Bu alan zorunludur.",+ "de": "Dieses Feld ist erforderlich.",+ "uk": "Це поле обов'язкове.",+ "ca": "Aquest camp és obligatori."+ },+ "SETUP$VALIDATION_MIN_LENGTH": {+ "en": "Must be at least {{length}} characters.",+ "ja": "{{length}} 文字以上で入力してください。",+ "zh-CN": "至少需要 {{length}} 个字符。",+ "zh-TW": "至少需要 {{length}} 個字元。",+ "ko-KR": "{{length}}자 이상이어야 합니다.",+ "no": "Må være minst {{length}} tegn.",+ "it": "Deve contenere almeno {{length}} caratteri.",+ "pt": "Deve ter pelo menos {{length}} caracteres.",+ "es": "Debe tener al menos {{length}} caracteres.",+ "ar": "يجب ألا يقل عن {{length}} حرفًا.",+ "fr": "Doit comporter au moins {{length}} caractères.",+ "tr": "En az {{length}} karakter olmalıdır.",+ "de": "Muss mindestens {{length}} Zeichen lang sein.",+ "uk": "Має містити щонайменше {{length}} символів.",+ "ca": "Ha de tenir com a mínim {{length}} caràcters."+ },+ "SETUP$VALIDATION_MAX_LENGTH": {+ "en": "Must be at most {{length}} characters.",+ "ja": "{{length}} 文字以内で入力してください。",+ "zh-CN": "最多 {{length}} 个字符。",+ "zh-TW": "最多 {{length}} 個字元。",+ "ko-KR": "{{length}}자 이하여야 합니다.",+ "no": "Kan være maks {{length}} tegn.",+ "it": "Deve contenere al massimo {{length}} caratteri.",+ "pt": "Deve ter no máximo {{length}} caracteres.",+ "es": "Debe tener como máximo {{length}} caracteres.",+ "ar": "يجب ألا يزيد عن {{length}} حرفًا.",+ "fr": "Doit comporter au maximum {{length}} caractères.",+ "tr": "En fazla {{length}} karakter olmalıdır.",+ "de": "Darf höchstens {{length}} Zeichen lang sein.",+ "uk": "Має містити не більше {{length}} символів.",+ "ca": "Ha de tenir com a màxim {{length}} caràcters."+ },+ "SETUP$VALIDATION_INVALID_OPTION": {+ "en": "Choose one of the available options.",+ "ja": "利用可能な選択肢から選んでください。",+ "zh-CN": "请从可用选项中选择。",+ "zh-TW": "請從可用選項中選擇。",+ "ko-KR": "사용 가능한 옵션 중에서 선택하세요.",+ "no": "Velg ett av de tilgjengelige alternativene.",+ "it": "Scegli una delle opzioni disponibili.",+ "pt": "Escolha uma das opções disponíveis.",+ "es": "Elige una de las opciones disponibles.",+ "ar": "اختر أحد الخيارات المتاحة.",+ "fr": "Choisissez l'une des options disponibles.",+ "tr": "Mevcut seçeneklerden birini seçin.",+ "de": "Wählen Sie eine der verfügbaren Optionen.",+ "uk": "Виберіть один із доступних варіантів.",+ "ca": "Trieu una de les opcions disponibles."+ },+ "SETUP$VALIDATION_UNSAFE_VALUE": {+ "en": "Quotes and backslashes are not allowed.",+ "ja": "引用符とバックスラッシュは使用できません。",+ "zh-CN": "不允许使用引号和反斜杠。",+ "zh-TW": "不允許使用引號和反斜線。",+ "ko-KR": "따옴표와 백슬래시는 사용할 수 없습니다.",+ "no": "Anførselstegn og omvendte skråstreker er ikke tillatt.",+ "it": "Le virgolette e le barre rovesciate non sono consentite.",+ "pt": "Aspas e barras invertidas não são permitidas.",+ "es": "No se permiten comillas ni barras invertidas.",+ "ar": "غير مسموح باستخدام علامات الاقتباس والشرطات المائلة العكسية.",+ "fr": "Les guillemets et les barres obliques inverses ne sont pas autorisés.",+ "tr": "Tırnak işaretleri ve ters eğik çizgiler kullanılamaz.",+ "de": "Anführungszeichen und Backslashes sind nicht zulässig.",+ "uk": "Лапки та зворотні скісні риски заборонені.",+ "ca": "No es permeten cometes ni barres invertides."+ },+ "SETUP$REVIEW_TITLE": {+ "en": "Review",+ "ja": "確認",+ "zh-CN": "确认",+ "zh-TW": "確認",+ "ko-KR": "검토",+ "no": "Se over",+ "it": "Rivedi",+ "pt": "Rever",+ "es": "Revisar",+ "ar": "مراجعة",+ "fr": "Vérifier",+ "tr": "Gözden geçir",+ "de": "Überprüfen",+ "uk": "Перевірка",+ "ca": "Revisa"+ },+ "SETUP$CONFIRM": {+ "en": "Confirm and create",+ "ja": "確認して作成",+ "zh-CN": "确认并创建",+ "zh-TW": "確認並建立",+ "ko-KR": "확인하고 만들기",+ "no": "Bekreft og opprett",+ "it": "Conferma e crea",+ "pt": "Confirmar e criar",+ "es": "Confirmar y crear",+ "ar": "تأكيد وإنشاء",+ "fr": "Confirmer et créer",+ "tr": "Onayla ve oluştur",+ "de": "Bestätigen und erstellen",+ "uk": "Підтвердити та створити",+ "ca": "Confirma i crea"+ },+ "SETUP$EMPTY_VALUE": {+ "en": "Not set",+ "ja": "未設定",+ "zh-CN": "未设置",+ "zh-TW": "未設定",+ "ko-KR": "설정되지 않음",+ "no": "Ikke angitt",+ "it": "Non impostato",+ "pt": "Não definido",+ "es": "Sin definir",+ "ar": "غير محدد",+ "fr": "Non défini",+ "tr": "Ayarlanmadı",+ "de": "Nicht festgelegt",+ "uk": "Не задано",+ "ca": "Sense definir"+ },+ "SETUP$UNSUPPORTED_MESSAGE": {+ "en": "This deployment does not support everything this automation needs.",+ "ja": "このデプロイメントは、このオートメーションが必要とする機能をすべてはサポートしていません。",+ "zh-CN": "此部署不支持该自动化所需的全部功能。",+ "zh-TW": "此部署不支援此自動化所需的全部功能。",+ "ko-KR": "이 배포는 이 자동화에 필요한 기능을 모두 지원하지 않습니다.",+ "no": "Denne installasjonen støtter ikke alt denne automatiseringen trenger.",+ "it": "Questa installazione non supporta tutto ciò che richiede questa automazione.",+ "pt": "Esta implementação não suporta tudo o que esta automatização necessita.",+ "es": "Esta instalación no admite todo lo que necesita esta automatización.",+ "ar": "لا تدعم هذه البيئة كل ما تحتاجه هذه الأتمتة.",+ "fr": "Ce déploiement ne prend pas en charge tout ce dont cette automatisation a besoin.",+ "tr": "Bu dağıtım, bu otomasyonun ihtiyaç duyduğu her şeyi desteklemiyor.",+ "de": "Diese Installation unterstützt nicht alles, was diese Automatisierung benötigt.",+ "uk": "Це середовище підтримує не все, що потрібно цій автоматизації.",+ "ca": "Aquest desplegament no admet tot el que necessita aquesta automatització."+ },+ "SETUP$REPOSITORY_PLACEHOLDER": {+ "en": "owner/repo",+ "ja": "owner/repo",+ "zh-CN": "owner/repo",+ "zh-TW": "owner/repo",+ "ko-KR": "owner/repo",+ "no": "owner/repo",+ "it": "owner/repo",+ "pt": "owner/repo",+ "es": "owner/repo",+ "ar": "owner/repo",+ "fr": "owner/repo",+ "tr": "owner/repo",+ "de": "owner/repo",+ "uk": "owner/repo",+ "ca": "owner/repo"}}diff --git a/src/manifests/automation-setup.ts b/src/manifests/automation-setup.tsnew file mode 100644index 0000000000..7b9a4c3791--- /dev/null+++ b/src/manifests/automation-setup.ts@@ -0,0 +1,216 @@+/**+ * The only module that knows a setup entry configures an *automation*.+ *+ * The published contract states just what varies between entries; everything+ * derivable is the host's to generate. That derivation is here, and nowhere+ * else, so the rest of `src/manifests/` stays about forms rather than about+ * automations.+ *+ * The algorithm mirrors `tests/test_automation_setup.py::_render_payload` in+ * `OpenHands/extensions`, which is the authoritative reference: it produces the+ * request bodies published in that repository's contract fixtures, and those+ * were verified against the live service. The create model is `extra="forbid"`,+ * so any divergence is a hard 422 rather than a dropped field.+ */++import { findAutomationCommand } from "#/utils/automation-catalog";+import { collectFields } from "./manifest-local-validation";+import { interpolateText } from "./manifest-template";+import type {+ SetupBlock,+ SetupEntry,+ SetupFormValues,+ SetupRequestBody,+ SetupTriggerKind,+} from "./types";++/** The creation endpoint a derived draft would be posted to. */+export const AUTOMATION_CREATE_ENDPOINT = "/v1/preset/prompt";++/**+ * Trigger properties a form field may fill, per trigger kind. A field under a+ * trigger kind whose name is listed here fills the trigger property of the same+ * name; anything else there, such as a phrase to match, is an input to `filter`.+ */+const TRIGGER_PROPERTIES: Record<SetupTriggerKind, readonly string[]> = {+ cron: ["schedule", "timezone"],+ event: ["on"],+};++/**+ * Repository properties a form field may fill, read the same way+ * {@link TRIGGER_PROPERTIES} is: a field whose name is listed here fills the+ * `repos[]` property of the same name. `url` and `provider` are absent because+ * neither is answered by a field of its own — they come from the repo-picker's+ * value and from its declared provider.+ *+ * These two lists are the only field names the derivation knows; everything+ * else it reads it finds by field type. An entry that wants a base branch in+ * its request therefore has to name that field `ref`.+ */+const REPO_PROPERTIES: readonly string[] = ["ref"];++const FORM_PLACEHOLDER_PATTERN = /\{\{form\.([A-Za-z0-9_.]+)\}\}/g;++/** The repository input, which supplies `repos` and an event trigger's source. */+function findRepoPickerField(setup: SetupBlock) {+ const match = Object.entries(collectFields(setup)).find(+ ([, field]) => field.type === "repo-picker",+ );+ return match ? { name: match[0], field: match[1] } : null;+}++/** The single trigger kind a direct entry declares, with its fields. */+function getTrigger(setup: SetupBlock) {+ const entries = Object.entries(setup.form.triggers ?? {});+ if (entries.length === 0) return null;+ const [kind, fields] = entries[0];+ return { kind: kind as SetupTriggerKind, fields: fields ?? {} };+}++/**+ * The create request body these form values produce.+ *+ * No entry declares it: `name` comes from the entry, `repos` from the+ * repo-picker field and its declared provider, and `trigger` from the key and+ * fields under `form.triggers`. Only `prompt` and an event `filter` are+ * declared, because only they cannot be read off the form.+ *+ * Returns null for an assisted entry, which hands setup to a conversation+ * instead of sending a body.+ */+export function buildCreatePayload(+ entry: SetupEntry,+ values: SetupFormValues,+): SetupRequestBody | null {+ const { setup } = entry;+ if (setup.mode !== "direct" || !setup.prompt) return null;++ const scope = { form: values, automation: entry };+ const repoPicker = findRepoPickerField(setup);+ const repository = repoPicker ? values[repoPicker.name] : undefined;++ const payload: SetupRequestBody = {+ name: repository ? `${entry.name} - ${repository}` : entry.name,+ prompt: interpolateText(setup.prompt, scope),+ };++ if (repository && repoPicker?.field.provider) {+ const declared = REPO_PROPERTIES.filter((name) => name in values);+ payload.repos = [+ {+ url: repository,+ ...Object.fromEntries(declared.map((name) => [name, values[name]])),+ provider: repoPicker.field.provider,+ },+ ];+ }++ const trigger = getTrigger(setup);+ if (trigger) {+ const properties = TRIGGER_PROPERTIES[trigger.kind];+ const declared = Object.keys(trigger.fields).filter((name) =>+ properties.includes(name),+ );++ payload.trigger = {+ type: trigger.kind,+ ...Object.fromEntries(declared.map((name) => [name, values[name] ?? ""])),+ ...(trigger.kind === "event" && {+ source: repoPicker?.field.provider ?? "",+ // A filter is optional: an entry that declares none accepts every+ // delivered event, so the key is left off rather than sent empty.+ ...(setup.filter && { filter: interpolateText(setup.filter, scope) }),+ }),+ };+ }++ return payload;+}++/**+ * The preflight body the host sends. The same shape for every entry, so no+ * entry declares it.+ */+export function buildPreflightBody(+ entry: SetupEntry,+ values: SetupFormValues,+): SetupRequestBody | null {+ const draft = buildCreatePayload(entry, values);+ if (!draft) return null;++ return {+ automationId: entry.id,+ endpoint: AUTOMATION_CREATE_ENDPOINT,+ draft,+ };+}++/**+ * What an assisted entry sends into the conversation that finishes setup.+ *+ * The command is not declared either: it lives once, in the owning skill's own+ * `triggers` frontmatter, and the skill defaults to the entry's id. An entry+ * whose skill is invoked by description rather than by command contributes+ * nothing here, and the answers alone open the conversation.+ */+export function buildAssistedMessage(+ entry: SetupEntry,+ values: SetupFormValues,+): string {+ const command = findAutomationCommand(entry);+ const message = entry.setup.message+ ? interpolateText(entry.setup.message, { form: values, automation: entry })+ : "";++ return [command, message].filter(Boolean).join("\n\n");+}++function collectPlaceholderFields(value: string): string[] {+ const names = Array.from(+ value.matchAll(FORM_PLACEHOLDER_PATTERN),+ (match) => match[1],+ );+ return Array.from(new Set(names));+}++/**+ * Which form fields built each payload path.+ *+ * Preflight and the create endpoint reject a draft by payload path, and the+ * host has to turn that back into a highlighted input. Building the body with+ * each field standing in for its own value recovers the mapping exactly, so an+ * entry does not declare it.+ */+export function deriveErrorMap(entry: SetupEntry): Record<string, string[]> {+ const mapping: Record<string, string[]> = {};++ const standIns = Object.fromEntries(+ Object.keys(collectFields(entry.setup)).map((name) => [+ name,+ `{{form.${name}}}`,+ ]),+ );+ const template = buildCreatePayload(entry, standIns);+ if (!template) return mapping;++ const walk = (node: unknown, path: string): void => {+ if (Array.isArray(node)) {+ node.forEach((item, index) => walk(item, `${path}[${index}]`));+ return;+ }+ if (typeof node === "object" && node !== null) {+ Object.entries(node).forEach(([key, item]) =>+ walk(item, path ? `${path}.${key}` : key),+ );+ return;+ }+ if (typeof node === "string") {+ const names = collectPlaceholderFields(node);+ if (names.length > 0) mapping[path] = names;+ }+ };++ walk(template, "");+ return mapping;+}diff --git a/src/manifests/manifest-actions.ts b/src/manifests/manifest-actions.tsnew file mode 100644index 0000000000..4f5daf88e2--- /dev/null+++ b/src/manifests/manifest-actions.ts@@ -0,0 +1,71 @@+/**+ * The action bridge — the only channel through which a manifest can make this+ * host *do* something.+ *+ * A manifest is data from another repository, so it never describes a request.+ * It chooses between the two outcomes this host offers, and it chooses by+ * declaring a `mode`: a direct entry produces a create request the host derives,+ * an assisted entry hands setup to a conversation.+ */++import { useCallback } from "react";+import AutomationService from "#/api/automation-service/automation-service.api";+import { useCreateConversation } from "#/hooks/mutation/use-create-conversation";+import { useConversationStore } from "#/stores/conversation-store";+import {+ setConversationState,+ setPendingTaskDraft,+} from "#/utils/conversation-local-storage";+import { buildAssistedMessage } from "./automation-setup";+import type { SetupEntry, SetupFormValues, SetupRequestBody } from "./types";++export interface SetupActionResult {+ /** The created resource, or the conversation that will finish setup. */+ response: Record<string, unknown>;+}++export function useSetupAction() {+ const createConversation = useCreateConversation();+ const setMessageToSend = useConversationStore(+ (state) => state.setMessageToSend,+ );++ const startConversation = useCallback(+ async (message: string): Promise<SetupActionResult> => {+ const conversation = await createConversation.mutateAsync({});++ // Seed the message the same way the rest of the app does, so the+ // conversation opens with it queued whichever launch path applies.+ if (+ conversation.conversation_id.startsWith("task-") &&+ conversation.task_id+ ) {+ setPendingTaskDraft(conversation.task_id, message);+ } else {+ setConversationState(conversation.conversation_id, {+ draftMessage: message,+ });+ }+ window.setTimeout(() => setMessageToSend(message), 0);++ return { response: { ...conversation } };+ },+ [createConversation, setMessageToSend],+ );++ return useCallback(+ async (+ entry: SetupEntry,+ values: SetupFormValues,+ /** Present for a direct entry, and absent for an assisted one. */+ payload: SetupRequestBody | null,+ ): Promise<SetupActionResult> => {+ if (!payload) {+ return startConversation(buildAssistedMessage(entry, values));+ }+ const response = await AutomationService.createAutomationDraft(payload);+ return { response };+ },+ [startConversation],+ );+}diff --git a/src/manifests/manifest-capabilities.ts b/src/manifests/manifest-capabilities.tsnew file mode 100644index 0000000000..b10c174ab2--- /dev/null+++ b/src/manifests/manifest-capabilities.ts@@ -0,0 +1,53 @@+/**+ * Stage 2 — decide whether a deployment can run what a manifest requires.+ *+ * The manifest states what it needs — the features under `requires.features`,+ * and, implicitly, the trigger kinds its form declares. The deployment states+ * what it supports. Neither side is interpreted here beyond set membership, so+ * this stays neutral about what any particular capability means.+ */++import type { DeploymentCapabilities, SetupEntry } from "./types";++/**+ * "unknown" is a real outcome, not an error: a deployment that cannot be asked+ * must not be treated as one that answered no.+ */+export type SetupCapabilitySupport = boolean | "unknown";++export interface SetupCapabilityAssessment {+ supported: boolean;+ /**+ * Requirement names the deployment did not report, so a block can say which+ * ones rather than only that there were some. Empty when a deployment that+ * reports it is not accepting work blocks the entry, because then no single+ * requirement is the reason.+ */+ unmet: string[];+}++function findUnreported(+ reported: readonly string[],+ required: readonly string[],+): string[] {+ return required.filter((entry) => !reported.includes(entry));+}++export function assessCapabilityRequirements(+ entry: SetupEntry,+ reported: DeploymentCapabilities,+): SetupCapabilityAssessment {+ // A deployment that is not accepting work blocks every entry, including one+ // that requires nothing of it.+ if (!reported.ready) return { supported: false, unmet: [] };++ const unmet = [+ ...findUnreported(reported.features ?? [], entry.requires.features ?? []),+ ...findUnreported(+ reported.triggerKinds ?? [],+ Object.keys(entry.setup.form.triggers ?? {}),+ ),+ ];++ return { supported: unmet.length === 0, unmet };+}diff --git a/src/manifests/manifest-error-map.ts b/src/manifests/manifest-error-map.tsnew file mode 100644index 0000000000..a2dc4e11b1--- /dev/null+++ b/src/manifests/manifest-error-map.ts@@ -0,0 +1,134 @@+/**+ * Translate service-reported errors back to the form field that produced them.+ *+ * The host validates and submits the *derived payload*, so errors come back+ * addressed by payload path (`trigger.schedule`) rather than by form field+ * (`schedule`). The reverse lookup is derived from the same builder that made+ * the payload; the mapping is lossy by nature, since one payload value can be+ * built from several fields.+ */++import type { SetupRequestBody } from "./types";++/** An error the service reported, addressed by payload path where it gave one. */+export interface ManifestServiceError {+ path: string;+ message: string;+}++export interface MappedManifestErrors {+ /** Keyed by form field name. */+ fieldErrors: Record<string, string>;+ /** Errors with no field to attach to; shown against the form as a whole. */+ formErrors: string[];+}++const EMPTY_MAPPED_ERRORS: MappedManifestErrors = {+ fieldErrors: {},+ formErrors: [],+};++function isRecord(value: unknown): value is Record<string, unknown> {+ return typeof value === "object" && value !== null && !Array.isArray(value);+}++/**+ * Turn a service `loc` array into a path into the payload actually sent.+ *+ * A validation framework may address a value through segments that are not keys+ * of the request body — a discriminated union reports+ * `["body","trigger","cron","schedule"]` for a body whose trigger has no `cron`+ * key. Walking the payload and skipping segments that do not resolve reduces+ * that to `trigger.schedule` without knowing anything about the payload's+ * meaning.+ */+export function locToPayloadPath(+ loc: readonly (string | number)[],+ payload: unknown,+): string {+ const segments = loc[0] === "body" ? loc.slice(1) : loc;+ const parts: string[] = [];+ let current: unknown = payload;++ segments.forEach((segment) => {+ if (typeof segment === "number") {+ if (Array.isArray(current) && parts.length > 0) {+ parts[parts.length - 1] += `[${segment}]`;+ current = current[segment];+ }+ return;+ }+ if (isRecord(current) && segment in current) {+ parts.push(segment);+ current = current[segment];+ }+ });++ return parts.join(".");+}++/**+ * Read errors out of a service response body, whichever of the two shapes it+ * uses: a preflight result keyed by field, or a validation failure keyed by+ * `loc`.+ */+export function normalizeServiceErrors(+ body: unknown,+ payload: SetupRequestBody | null,+): ManifestServiceError[] {+ if (!isRecord(body)) return [];++ if (Array.isArray(body.errors)) {+ return body.errors.flatMap((entry) => {+ if (!isRecord(entry) || typeof entry.message !== "string") return [];+ return [+ {+ path: typeof entry.field === "string" ? entry.field : "",+ message: entry.message,+ },+ ];+ });+ }++ const { detail } = body;+ if (typeof detail === "string") {+ return [{ path: "", message: detail }];+ }+ if (Array.isArray(detail)) {+ return detail.flatMap((entry) => {+ if (!isRecord(entry) || typeof entry.msg !== "string") return [];+ const loc = Array.isArray(entry.loc)+ ? (entry.loc as (string | number)[])+ : [];+ return [{ path: locToPayloadPath(loc, payload), message: entry.msg }];+ });+ }++ return [];+}++/** Apply the derived payload-path map, falling back to a form-level error. */+export function mapServiceErrors(+ errors: readonly ManifestServiceError[],+ errorMap: Record<string, string[]>,+): MappedManifestErrors {+ if (errors.length === 0) return EMPTY_MAPPED_ERRORS;++ const fieldErrors: Record<string, string> = {};+ const formErrors: string[] = [];++ errors.forEach(({ path, message }) => {+ const fields = path ? errorMap[path] : undefined;+ if (!fields?.length) {+ formErrors.push(message);+ return;+ }+ fields.forEach((field) => {+ // Keep the first error reported against a field; later ones would+ // silently replace a message the user has not read yet.+ if (!(field in fieldErrors)) fieldErrors[field] = message;+ });+ });++ return { fieldErrors, formErrors };+}diff --git a/src/manifests/manifest-local-validation.ts b/src/manifests/manifest-local-validation.tsnew file mode 100644index 0000000000..b34b54a85e--- /dev/null+++ b/src/manifests/manifest-local-validation.ts@@ -0,0 +1,146 @@+/**+ * The form model, and the host's own check of what the user typed into it.+ *+ * Local validation is a convenience, not the authority: it is instant and needs+ * no round trip, so it catches empty required fields and obvious typos.+ * Deployment-specific questions ("is a one-minute schedule allowed here?")+ * belong to preflight, which is authoritative.+ *+ * Errors are returned as codes rather than sentences so the host can render+ * them through its own translations; only manifest-authored copy is literal.+ */++import type {+ DeploymentCapabilities,+ SetupBlock,+ SetupFieldOption,+ SetupFormField,+ SetupFormFields,+ SetupFormValues,+} from "./types";++/** Characters that would break out of an expression string literal. */+const UNSAFE_EXPRESSION_LITERAL_PATTERN = /["'\\]/;++export type SetupFieldError =+ | { code: "required" }+ | { code: "minLength"; length: number }+ | { code: "maxLength"; length: number }+ | { code: "invalidOption" }+ | { code: "unsafeExpressionLiteral" };++export type SetupFieldErrors = Record<string, SetupFieldError>;++/** Field constraints supplied by the deployment rather than by the manifest. */+export interface SetupFieldOverride {+ options?: SetupFieldOption[];+}++export type SetupFieldOverrides = Record<string, SetupFieldOverride>;++/**+ * Every input the form declares, keyed by name, whichever half it is in.+ *+ * Trigger inputs come first so the user is asked when it runs before what it+ * runs on, and so every derived view of the form keeps that order. Admission+ * rejects a name declared in both halves, so the merge cannot lose a field.+ */+export function collectFields(setup: SetupBlock): SetupFormFields {+ const triggers = Object.values(setup.form.triggers ?? {});+ return Object.assign({}, ...triggers, setup.form.args) as SetupFormFields;+}++/**+ * Feed deployment values into form field constraints, so the form offers only+ * what the deployment accepts.+ *+ * A `timezone` field is the case that needs it: a manifest declares no options+ * for one, because the accepted zones belong to the deployment. The cron+ * interval floor is deliberately left to preflight — the deployment owns that+ * limit and states it in its own words, and a local approximation would+ * pre-empt the authoritative message with a worse one.+ */+export function resolveFieldOverrides(+ setup: SetupBlock,+ capabilities: DeploymentCapabilities | null,+): SetupFieldOverrides {+ const timezones = capabilities?.triggers?.cron?.timezones;+ if (!timezones?.length) return {};++ const options = timezones.map((zone) => ({ value: zone, label: zone }));+ return Object.fromEntries(+ Object.entries(collectFields(setup))+ .filter(([, field]) => field.type === "timezone")+ .map(([name]) => [name, { options }]),+ );+}++/** The options a field offers, after deployment constraints are applied. */+export function getFieldOptions(+ name: string,+ field: SetupFormField,+ overrides: SetupFieldOverrides = {},+): SetupFieldOption[] {+ return overrides[name]?.options ?? field.options ?? [];+}++/** Initial form state: every declared field, seeded with its declared default. */+export function getInitialFormValues(setup: SetupBlock): SetupFormValues {+ return Object.fromEntries(+ Object.entries(collectFields(setup)).map(([name, field]) => [+ name,+ field.default ?? "",+ ]),+ );+}++function validateField(+ name: string,+ field: SetupFormField,+ rawValue: string | undefined,+ overrides: SetupFieldOverrides,+): SetupFieldError | null {+ const value = (rawValue ?? "").trim();++ if (!value) {+ return field.required ? { code: "required" } : null;+ }++ const { minLength, maxLength, format } = field.constraints ?? {};+ if (minLength !== undefined && value.length < minLength) {+ return { code: "minLength", length: minLength };+ }+ if (maxLength !== undefined && value.length > maxLength) {+ return { code: "maxLength", length: maxLength };+ }+ if (+ format === "safeExpressionLiteral" &&+ UNSAFE_EXPRESSION_LITERAL_PATTERN.test(value)+ ) {+ return { code: "unsafeExpressionLiteral" };+ }++ // Any field offering a closed set of values, whether the manifest declared it+ // or the deployment supplied it, must be answered from that set.+ const options = getFieldOptions(name, field, overrides);+ if (options.length > 0 && !options.some((option) => option.value === value)) {+ return { code: "invalidOption" };+ }++ return null;+}++/** Check every declared field. Returns only the fields that failed. */+export function validateFormValues(+ setup: SetupBlock,+ values: SetupFormValues,+ overrides: SetupFieldOverrides = {},+): SetupFieldErrors {+ return Object.entries(collectFields(setup)).reduce<SetupFieldErrors>(+ (errors, [name, field]) => {+ const error = validateField(name, field, values[name], overrides);+ return error ? { ...errors, [name]: error } : errors;+ },+ {},+ );+}diff --git a/src/manifests/manifest-registry.ts b/src/manifests/manifest-registry.tsnew file mode 100644index 0000000000..1d5afd1fa4--- /dev/null+++ b/src/manifests/manifest-registry.ts@@ -0,0 +1,52 @@+/**+ * Registry of admitted setup manifests.+ *+ * Stage 1 of the setup flow: load the catalog, decide which entries this host+ * will act on, and index the survivors by id. An entry that fails admission is+ * dropped entirely rather than rendered partially, because everything+ * downstream treats its content as instructions.+ */++import { hasSetupBlock, validateSetupEntry } from "./manifest-validation";+import type { SetupEntry } from "./types";++export interface SetupRegistry {+ /** Entries this host has admitted, in source order. */+ readonly entries: readonly SetupEntry[];+ findById(id: string): SetupEntry | null;+}++export function createSetupRegistry(+ candidates: readonly unknown[],+): SetupRegistry {+ const entries: SetupEntry[] = [];+ const byId = new Map<string, SetupEntry>();++ candidates.forEach((candidate) => {+ // A catalog entry without a setup block is a card, not a setup experience.+ // That is the normal case, so it is skipped rather than reported.+ if (!hasSetupBlock(candidate)) return;++ const { valid, errors } = validateSetupEntry(candidate);+ if (!valid) {+ console.warn("Rejected a setup manifest:", errors.join("; "));+ return;+ }++ const entry = candidate as SetupEntry;+ if (byId.has(entry.id)) {+ console.warn(+ `Rejected a setup manifest: id "${entry.id}" is already registered`,+ );+ return;+ }++ entries.push(entry);+ byId.set(entry.id, entry);+ });++ return {+ entries,+ findById: (id) => byId.get(id) ?? null,+ };+}diff --git a/src/manifests/manifest-sources.ts b/src/manifests/manifest-sources.tsnew file mode 100644index 0000000000..1932177bca--- /dev/null+++ b/src/manifests/manifest-sources.ts@@ -0,0 +1,19 @@+/**+ * The one place that decides which manifests this host is offered.+ *+ * Setup manifests are published by `@openhands/extensions` as an optional+ * `setup` block on a catalog entry, so the catalog is the whole source. Entries+ * without one are skipped, which means the pinned package deciding to ship them+ * is the only step left — there is no wiring to add here.+ *+ * The catalog is passed as `unknown[]` on purpose: admission is a trust+ * boundary, so the host validates the published data rather than trusting the+ * types that shipped beside it.+ */++import { AUTOMATION_CATALOG } from "@openhands/extensions/automations";+import { createSetupRegistry, type SetupRegistry } from "./manifest-registry";++export const SETUP_REGISTRY: SetupRegistry = createSetupRegistry(+ AUTOMATION_CATALOG as readonly unknown[],+);diff --git a/src/manifests/manifest-template.ts b/src/manifests/manifest-template.tsnew file mode 100644index 0000000000..904228c4b3--- /dev/null+++ b/src/manifests/manifest-template.ts@@ -0,0 +1,42 @@+/**+ * Placeholder interpolation for setup copy and request-body strings.+ *+ * A setup block declares what the user sees and the two request strings the+ * host cannot derive as templates over a small set of namespaces. Interpolation+ * is plain substitution — there is no expression language, so a setup block+ * cannot express behavior here.+ */++import type { SetupEntry, SetupFormValues } from "./types";++const PLACEHOLDER_PATTERN = /\{\{([A-Za-z0-9_]+(?:\.[A-Za-z0-9_]+)*)\}\}/g;++export interface SetupScope {+ form?: SetupFormValues;+ /** The catalog entry the setup block belongs to. */+ automation?: SetupEntry;+}++/** Walk a dotted path through plain objects. */+export function getByPath(source: unknown, path: string): unknown {+ return path.split(".").reduce<unknown>((current, segment) => {+ if (typeof current !== "object" || current === null) return undefined;+ return (current as Record<string, unknown>)[segment];+ }, source);+}++function toText(value: unknown): string {+ if (typeof value === "string") return value;+ if (typeof value === "number" || typeof value === "boolean") {+ return String(value);+ }+ // Missing values render as blank; callers that care show their own fallback.+ return "";+}++/** Substitute placeholders inside a template string. */+export function interpolateText(template: string, scope: SetupScope): string {+ return template.replace(PLACEHOLDER_PATTERN, (_match, path: string) =>+ toText(getByPath(scope, path)),+ );+}diff --git a/src/manifests/manifest-validation.ts b/src/manifests/manifest-validation.tsnew file mode 100644index 0000000000..f0f6a4190b--- /dev/null+++ b/src/manifests/manifest-validation.ts@@ -0,0 +1,414 @@+/**+ * Admission policy for extension-authored catalog manifests.+ *+ * A manifest is data authored in a different repository that instructs this host+ * to render copy and compose a request. The host therefore decides what a+ * manifest is *permitted* to do rather than trusting the file — validation here+ * is a trust boundary, not a convenience check, and it deliberately does not+ * defer to a schema shipped alongside the manifests it would be validating.+ *+ * Beyond mirroring the published schema, this adds the invariants the host's own+ * derivation depends on: a single trigger kind to read, a repository field for+ * an event trigger's source, and field names unique across the form. Without+ * them the derived request body would be silently wrong rather than rejected.+ *+ * A manifest that fails any check is rejected outright. It never renders a+ * partial UI, because everything downstream treats its content as instructions.+ */++import { SETUP_PLACEHOLDER_NAMESPACES, SETUP_VERSION } from "./types";++const ENTRY_ID_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;+const FIELD_NAME_PATTERN = /^[a-z][A-Za-z0-9]*$/;+/** Copy must never be able to inject markup into the host. */+const MARKUP_PATTERN = /<[A-Za-z/!]/;+/** Every `{{` must open a known namespace and close immediately. */+const UNKNOWN_PLACEHOLDER_PATTERN = new RegExp(+ `\\{\\{(?!(?:${SETUP_PLACEHOLDER_NAMESPACES.join("|")})\\.[A-Za-z0-9_.]+\\}\\})`,+);++const SETUP_MODES = ["direct", "assisted"] as const;+const FIELD_TYPES = [+ "text",+ "textarea",+ "select",+ "cron",+ "timezone",+ "repo-picker",+] as const;+const GIT_PROVIDERS = ["github", "gitlab", "bitbucket"] as const;+const TRIGGER_KINDS = ["cron", "event"] as const;+const CONSTRAINT_FORMATS = ["safeExpressionLiteral"] as const;++/** Setup context only, so this can never become a channel for runtime instructions. */+const MAX_ASSISTED_MESSAGE_LENGTH = 2000;++export interface SetupValidationResult {+ valid: boolean;+ errors: string[];+}++type Rec = Record<string, unknown>;++function isRecord(value: unknown): value is Rec {+ return typeof value === "object" && value !== null && !Array.isArray(value);+}++function isOneOf<T extends readonly string[]>(+ value: unknown,+ allowed: T,+): value is T[number] {+ return (+ typeof value === "string" && (allowed as readonly string[]).includes(value)+ );+}++function isInteger(value: unknown, minimum: number): boolean {+ return (+ typeof value === "number" && Number.isInteger(value) && value >= minimum+ );+}++class SetupChecker {+ readonly errors: string[] = [];++ fail(path: string, reason: string): false {+ this.errors.push(`${path}: ${reason}`);+ return false;+ }++ /** Literal user-visible copy. Carries no markup. */+ copy(value: unknown, path: string): boolean {+ if (typeof value !== "string" || value.length === 0) {+ return this.fail(path, "must be a non-empty string");+ }+ if (MARKUP_PATTERN.test(value)) {+ return this.fail(path, "must not contain markup");+ }+ return true;+ }++ placeholders(value: string, path: string): boolean {+ if (UNKNOWN_PLACEHOLDER_PATTERN.test(value)) {+ return this.fail(path, "uses an unknown placeholder namespace");+ }+ return true;+ }++ /** Copy that may embed `{{namespace.key}}` placeholders. */+ templateCopy(value: unknown, path: string): boolean {+ return this.copy(value, path) && this.placeholders(value as string, path);+ }++ /**+ * A request-body string that may embed placeholders. Never rendered, so+ * expression syntax such as a JMESPath filter is allowed through.+ */+ templateValue(value: unknown, path: string): boolean {+ if (typeof value !== "string" || value.length === 0) {+ return this.fail(path, "must be a non-empty string");+ }+ return this.placeholders(value, path);+ }++ absent(container: Rec, key: string, path: string, reason: string): boolean {+ if (key in container) return this.fail(`${path}.${key}`, reason);+ return true;+ }+}++function checkRequires(check: SetupChecker, requires: unknown): void {+ if (!isRecord(requires)) {+ check.fail("requires", "must be an object");+ return;+ }++ const { integrations, features } = requires;+ if (!isRecord(integrations) || Object.keys(integrations).length === 0) {+ check.fail("requires.integrations", "must be a non-empty object");+ } else {+ Object.entries(integrations).forEach(([id, requirement]) => {+ const path = `requires.integrations.${id}`;+ if (!isRecord(requirement)) {+ check.fail(path, "must be an object");+ return;+ }+ check.copy(requirement.message, `${path}.message`);+ if ("required" in requirement && requirement.required !== false) {+ check.fail(`${path}.required`, "may only be false");+ }+ const allowed = ["message", "required"];+ Object.keys(requirement)+ .filter((key) => !allowed.includes(key))+ .forEach((key) => check.fail(`${path}.${key}`, "is not allowed"));+ });+ }++ if (features !== undefined) {+ if (!Array.isArray(features) || features.length === 0) {+ check.fail("requires.features", "must be a non-empty array");+ } else {+ features.forEach((feature, index) => {+ if (typeof feature !== "string" || feature.length === 0) {+ check.fail(+ `requires.features[${index}]`,+ "must be a non-empty string",+ );+ }+ });+ }+ }+}++function checkConstraints(+ check: SetupChecker,+ constraints: unknown,+ path: string,+): void {+ if (!isRecord(constraints) || Object.keys(constraints).length === 0) {+ check.fail(path, "must be a non-empty object");+ return;+ }++ const { minLength, maxLength, format } = constraints;+ if (minLength !== undefined && !isInteger(minLength, 0)) {+ check.fail(`${path}.minLength`, "must be a non-negative integer");+ }+ if (maxLength !== undefined && !isInteger(maxLength, 1)) {+ check.fail(`${path}.maxLength`, "must be a positive integer");+ }+ if (format !== undefined && !isOneOf(format, CONSTRAINT_FORMATS)) {+ check.fail(`${path}.format`, "is not a supported format");+ }+}++function checkField(check: SetupChecker, field: unknown, path: string): void {+ if (!isRecord(field)) {+ check.fail(path, "must be an object");+ return;+ }++ const { type, label, help, placeholder, required, provider, options } = field;++ if (!isOneOf(type, FIELD_TYPES)) {+ check.fail(`${path}.type`, "is not a supported field type");+ }+ check.copy(label, `${path}.label`);+ check.copy(help, `${path}.help`);+ if (placeholder !== undefined) check.copy(placeholder, `${path}.placeholder`);+ if (field.default !== undefined && typeof field.default !== "string") {+ check.fail(`${path}.default`, "must be a string");+ }+ if (typeof required !== "boolean") {+ check.fail(`${path}.required`, "must be a boolean");+ }+ if (provider !== undefined && !isOneOf(provider, GIT_PROVIDERS)) {+ check.fail(`${path}.provider`, "is not a supported provider");+ }+ if (type === "repo-picker" && provider === undefined) {+ check.fail(`${path}.provider`, "is required for a repository field");+ }++ if (options !== undefined) {+ if (type !== "select") {+ check.fail(`${path}.options`, "is only allowed on a select field");+ } else if (!Array.isArray(options) || options.length === 0) {+ check.fail(`${path}.options`, "must be a non-empty array");+ } else {+ options.forEach((option, index) => {+ const optionPath = `${path}.options[${index}]`;+ if (!isRecord(option)) {+ check.fail(optionPath, "must be an object");+ return;+ }+ if (typeof option.value !== "string" || option.value.length === 0) {+ check.fail(`${optionPath}.value`, "must be a non-empty string");+ }+ check.copy(option.label, `${optionPath}.label`);+ });+ }+ }++ if (field.constraints !== undefined) {+ checkConstraints(check, field.constraints, `${path}.constraints`);+ }+}++/** Returns the declared field names, so the caller can check them for collisions. */+function checkFields(+ check: SetupChecker,+ fields: unknown,+ path: string,+): string[] {+ if (!isRecord(fields) || Object.keys(fields).length === 0) {+ check.fail(path, "must be a non-empty object");+ return [];+ }++ return Object.entries(fields).map(([name, field]) => {+ if (!FIELD_NAME_PATTERN.test(name)) {+ check.fail(`${path}.${name}`, "is not a valid field name");+ }+ checkField(check, field, `${path}.${name}`);+ return name;+ });+}++/** Returns the trigger kinds declared, in order. */+function checkForm(check: SetupChecker, form: unknown): string[] {+ if (!isRecord(form)) {+ check.fail("setup.form", "must be an object");+ return [];+ }++ if (form.note !== undefined) check.copy(form.note, "setup.form.note");++ const names = checkFields(check, form.args, "setup.form.args");+ const kinds: string[] = [];++ if (form.triggers !== undefined) {+ if (!isRecord(form.triggers) || Object.keys(form.triggers).length === 0) {+ check.fail("setup.form.triggers", "must be a non-empty object");+ } else {+ Object.entries(form.triggers).forEach(([kind, fields]) => {+ if (!isOneOf(kind, TRIGGER_KINDS)) {+ check.fail(`setup.form.triggers.${kind}`, "is not a trigger kind");+ return;+ }+ kinds.push(kind);+ names.push(+ ...checkFields(check, fields, `setup.form.triggers.${kind}`),+ );+ });+ }+ }++ // The host merges both halves into one value map, so a repeated name would+ // silently shadow a field and misaddress every error reported against it.+ const duplicates = names.filter(+ (name, index) => names.indexOf(name) !== index,+ );+ Array.from(new Set(duplicates)).forEach((name) =>+ check.fail(`setup.form.${name}`, "is declared more than once"),+ );++ return kinds;+}++function hasRepoPicker(form: unknown): boolean {+ if (!isRecord(form)) return false;+ const groups = [+ form.args,+ ...Object.values(isRecord(form.triggers) ? form.triggers : {}),+ ];+ return groups.some(+ (group) =>+ isRecord(group) &&+ Object.values(group).some(+ (field) => isRecord(field) && field.type === "repo-picker",+ ),+ );+}++function checkMode(check: SetupChecker, setup: Rec, kinds: string[]): void {+ if (!isOneOf(setup.mode, SETUP_MODES)) {+ check.fail("setup.mode", "is not a supported mode");+ return;+ }++ if (setup.mode === "direct") {+ check.templateValue(setup.prompt, "setup.prompt");+ check.absent(+ setup,+ "message",+ "setup",+ "is only allowed for assisted setup",+ );++ // The derivation reads a single trigger kind, and an event trigger takes+ // its source from the repository field's provider.+ if (kinds.length !== 1) {+ check.fail(+ "setup.form.triggers",+ "must declare exactly one trigger kind",+ );+ }+ if (kinds.includes("event") && !hasRepoPicker(setup.form)) {+ check.fail(+ "setup.form",+ "must declare a repository field for an event trigger",+ );+ }+ if (setup.filter !== undefined) {+ if (!kinds.includes("event")) {+ check.fail("setup.filter", "is only allowed for an event trigger");+ } else {+ check.templateValue(setup.filter, "setup.filter");+ }+ }+ return;+ }++ if (check.templateCopy(setup.message, "setup.message")) {+ if ((setup.message as string).length > MAX_ASSISTED_MESSAGE_LENGTH) {+ check.fail(+ "setup.message",+ `must be at most ${MAX_ASSISTED_MESSAGE_LENGTH} characters`,+ );+ }+ }+ check.absent(setup, "prompt", "setup", "is only allowed for direct setup");+ check.absent(setup, "filter", "setup", "is only allowed for direct setup");+}++/** Whether a catalog entry ships a setup experience at all. It is optional. */+export function hasSetupBlock(candidate: unknown): boolean {+ return isRecord(candidate) && candidate.setup !== undefined;+}++/**+ * Decide whether this host will act on a catalog manifest.+ *+ * The version is checked first and fails closed: a format this host does not+ * recognise is refused rather than interpreted with today's rules.+ */+export function validateSetupEntry(candidate: unknown): SetupValidationResult {+ const check = new SetupChecker();++ if (!isRecord(candidate)) {+ return { valid: false, errors: ["manifest: must be an object"] };+ }++ const { setup } = candidate;+ if (!isRecord(setup)) {+ return { valid: false, errors: ["setup: must be an object"] };+ }+ if (setup.version !== SETUP_VERSION) {+ return {+ valid: false,+ errors: [`setup.version: must be "${SETUP_VERSION}"`],+ };+ }++ if (+ typeof candidate.id !== "string" ||+ !ENTRY_ID_PATTERN.test(candidate.id)+ ) {+ check.fail("id", "must be a lowercase slug");+ }+ check.copy(candidate.name, "name");+ check.copy(candidate.description, "description");+ if (+ candidate.skill !== undefined &&+ (typeof candidate.skill !== "string" ||+ !ENTRY_ID_PATTERN.test(candidate.skill))+ ) {+ check.fail("skill", "must be a lowercase slug");+ }++ checkRequires(check, candidate.requires);+ const kinds = checkForm(check, setup.form);+ checkMode(check, setup, kinds);++ return { valid: check.errors.length === 0, errors: check.errors };+}diff --git a/src/manifests/types.ts b/src/manifests/types.tsnew file mode 100644index 0000000000..e5f670364d--- /dev/null+++ b/src/manifests/types.ts@@ -0,0 +1,151 @@+/**+ * Host-owned shape of an extension-authored setup experience.+ *+ * A catalog entry is declarative data published by `@openhands/extensions`. Its+ * optional `setup` block says what to ask a user for; everything derivable from+ * that — the request to send, the route, the review screen, the analytics — is+ * this host's to generate, so none of it appears here.+ *+ * The names mirror `@openhands/extensions/automations`' own declarations, so an+ * entry from the published package assigns without an adapter.+ */++export const SETUP_VERSION = "1.0";++export type SetupMode = "direct" | "assisted";++export type SetupFieldType =+ | "text"+ | "textarea"+ | "select"+ | "cron"+ | "timezone"+ | "repo-picker";++export type SetupGitProvider = "github" | "gitlab" | "bitbucket";++export type SetupTriggerKind = "cron" | "event";++/** Placeholder namespaces a setup block may reference inside `{{...}}`. */+export const SETUP_PLACEHOLDER_NAMESPACES = ["form", "automation"] as const;++export interface SetupFieldOption {+ value: string;+ label: string;+}++export interface SetupFieldConstraints {+ minLength?: number;+ maxLength?: number;+ /**+ * A host-implemented check named from a closed set. Entries supply no regex+ * of their own, so they cannot hand the host a pathological pattern.+ */+ format?: "safeExpressionLiteral";+}++export interface SetupFormField {+ type: SetupFieldType;+ label: string;+ help: string;+ placeholder?: string;+ default?: string;+ required: boolean;+ provider?: SetupGitProvider;+ options?: SetupFieldOption[];+ constraints?: SetupFieldConstraints;+}++/** Keyed by field name, which is what `{{form.<name>}}` resolves against. */+export type SetupFormFields = Record<string, SetupFormField>;++export interface SetupForm {+ note?: string;+ /** Inputs that decide when the automation runs, keyed by trigger kind. */+ triggers?: Partial<Record<SetupTriggerKind, SetupFormFields>>;+ /** Every other input: the arguments to the automation itself. */+ args: SetupFormFields;+}++export interface SetupBlock {+ version: typeof SETUP_VERSION;+ mode: SetupMode;+ form: SetupForm;+ /** 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 interface SetupIntegrationRequirement {+ /** Why this entry needs the integration. */+ message: string;+ /** Defaults to true. `false` lets setup continue while it is unconnected. */+ required?: false;+}++export interface SetupPrerequisites {+ /** Keyed by integration catalog id. */+ integrations: Record<string, SetupIntegrationRequirement>;+ /** Deployment capabilities this entry cannot run without. */+ features?: string[];+}++/**+ * The part of a catalog entry this host reads. An admitted entry always has a+ * `setup` block; entries without one are simply not setup entries.+ */+export interface SetupEntry {+ id: string;+ name: string;+ description: string;+ requires: SetupPrerequisites;+ /** The skill that owns the launch command. Defaults to `id`. */+ skill?: string;+ setup: SetupBlock;+}++export type SetupPayloadValue =+ | string+ | number+ | boolean+ | null+ | SetupPayloadValue[]+ | { [key: string]: SetupPayloadValue };++export interface SetupRequestBody {+ [key: string]: SetupPayloadValue;+}++/** Form values are collected as strings; the payload mapping shapes them. */+export type SetupFormValues = Record<string, string>;++/** `GET /v1/capabilities` — what this deployment supports. */+export interface DeploymentCapabilities {+ ready: boolean;+ triggerKinds: string[];+ eventSources: string[];+ eventTypes: string[];+ triggers: {+ cron?: { minIntervalSeconds: number; timezones: string[] };+ event?: { filterLanguage: string; filterFunctions: string[] };+ };+ features: string[];+}++/** A single problem with a draft, addressed to the field that caused it. */+export interface DraftValidationError {+ /** Dotted path into the draft. Null when the problem spans the whole draft. */+ field: string | null;+ code: string;+ message: string;+}++/** `POST /v1/validate` — an invalid draft is still a 200. */+export interface ValidateDraftResponse {+ valid: boolean;+ errors: DraftValidationError[];+ sampleEventMatched?: boolean | null;+}diff --git a/src/routes.ts b/src/routes.tsindex dbab4ee202..d77c84173d 100644--- a/src/routes.ts+++ b/src/routes.ts@@ -32,6 +32,7 @@ export default []),route("oauth/device/verify", "routes/device-verify.tsx"),route("automations", "routes/automations-list.tsx"),+ route("automations/new/:automationId", "routes/automation-setup-route.tsx"),route("automations/:automationId", "routes/automation-detail.tsx"),]),route(diff --git a/src/routes/automation-setup-route.tsx b/src/routes/automation-setup-route.tsxnew file mode 100644index 0000000000..e3037c2ca9--- /dev/null+++ b/src/routes/automation-setup-route.tsx@@ -0,0 +1,42 @@+import { useLoaderData, useLocation, useNavigate } from "react-router";+import { Route } from "./+types/automation-setup-route";+import { SETUP_REGISTRY } from "#/manifests/manifest-sources";+import { SetupDialog } from "#/components/features/manifest/manifest-setup-dialog";++/** Where dismissing lands when the dialog was opened by a cold deep link. */+const FALLBACK_PATH = "/automations";++/**+ * Setup for one catalog entry.+ *+ * The path is not declared by the manifest: it is the same shape for every+ * entry, so the host derives it from the id. An id no entry claims — or one+ * whose manifest failed admission — is a 404, which the layout's existing+ * error boundary renders.+ */+export const clientLoader = ({ params }: Route.ClientLoaderArgs) => {+ const entry = SETUP_REGISTRY.findById(params.automationId ?? "");++ if (!entry) {+ throw new Response(null, { status: 404, statusText: "Not Found" });+ }++ return { automationId: entry.id };+};++export default function AutomationSetupRoute() {+ const { automationId } = useLoaderData<typeof clientLoader>();+ const location = useLocation();+ const navigate = useNavigate();++ const entry = SETUP_REGISTRY.findById(automationId);+ if (!entry) return null;++ const handleClose = () => {+ // "default" is the initial history entry, so there is nothing to go back to.+ if (location.key === "default") navigate(FALLBACK_PATH, { replace: true });+ else navigate(-1);+ };++ return <SetupDialog entry={entry} onClose={handleClose} />;+}diff --git a/src/utils/api-error-message.ts b/src/utils/api-error-message.tsindex 015c1f6ecd..b927e51cca 100644--- a/src/utils/api-error-message.ts+++ b/src/utils/api-error-message.ts@@ -1,21 +1,28 @@import axios from "axios";/**- * Extract a human-readable message from a failed API call.+ * Extract the parsed response body from a failed API call.** Handles both transports the app uses: local agent-server calls that* throw an `AxiosError` (body under `error.response.data`) and cloud* calls through the shared TypeScript client that throw an `HttpError`- * (parsed body directly under `error.response`). Prefers the+ * (parsed body directly under `error.response`).+ */+export function getApiErrorBody(error: unknown): unknown {+ if (axios.isAxiosError(error)) return error.response?.data;+ if (error instanceof Error && "response" in error) {+ return (error as { response?: unknown }).response;+ }+ return undefined;+}++/**+ * Extract a human-readable message from a failed API call. Prefers the* server-provided `message`/`detail` fields, then the `Error` message,* then `fallback`.*/export function getApiErrorMessage(error: unknown, fallback: string): string {- const body = axios.isAxiosError(error)- ? error.response?.data- : error instanceof Error && "response" in error- ? (error as { response?: unknown }).response- : undefined;+ const body = getApiErrorBody(error);if (body && typeof body === "object") {const { message, detail } = body as {diff --git a/src/utils/automation-catalog.ts b/src/utils/automation-catalog.tsnew file mode 100644index 0000000000..88187a4d50--- /dev/null+++ b/src/utils/automation-catalog.ts@@ -0,0 +1,70 @@+import type { RecommendedAutomation } from "@openhands/extensions/automations";+import {+ SKILLS_CATALOG,+ type SkillCatalogEntry,+} from "@openhands/extensions/skills";++/**+ * Reading a published automation catalog entry.+ *+ * The catalog states each thing once and leaves the rest to be derived, so an+ * entry no longer carries its own launch command or a flat list of required+ * integration ids. This module is the single place that performs those+ * derivations, so the components consuming the catalog stay unaware of how it+ * is shaped.+ */++const SKILL_BY_NAME = new Map<string, SkillCatalogEntry>(+ SKILLS_CATALOG.map((skill) => [skill.name, skill]),+);++/** Every integration the entry declares, in declaration order. */+export function getIntegrationIds(automation: RecommendedAutomation): string[] {+ return Object.keys(automation.requires.integrations);+}++/**+ * The integrations that gate this automation. One marked `required: false` can+ * be connected later, during setup, so it is still worth showing on the card+ * but must never stand between the user and a launch.+ */+export function getRequiredIntegrationIds(+ automation: RecommendedAutomation,+): string[] {+ return Object.entries(automation.requires.integrations)+ .filter(([, requirement]) => requirement.required !== false)+ .map(([id]) => id);+}++/**+ * The command that invokes this automation's skill, or null when that skill is+ * invoked by description instead.+ *+ * The command is declared once, in the owning skill's own `triggers`; the+ * catalog names that skill only where it differs from the entry id.+ */+export function findAutomationCommand(+ automation: Pick<RecommendedAutomation, "id" | "skill">,+): string | null {+ const skill = SKILL_BY_NAME.get(automation.skill ?? automation.id);+ return skill?.triggers[0] ?? null;+}++/**+ * What launching an automation card hands to the agent.+ *+ * The resolved command is passed through as-is: API routing (host, auth) is+ * discovered by the agent at runtime from `<RUNTIME_SERVICES>` in the system+ * prompt, and the skills themselves carry the instructions for reading that+ * block. An automation whose skill declares no command has the request spelled+ * out instead. Both are instructions to the agent rather than user-facing UI+ * copy, so they are intentionally in English and not localized.+ */+export function getAutomationLaunchPrompt(+ automation: RecommendedAutomation,+): string {+ return (+ findAutomationCommand(automation) ??+ `Set up the ${automation.name} automation`+ );+}diff --git a/src/utils/responder-deployment.ts b/src/utils/responder-deployment.tsindex f116bf81b9..4d9ece9282 100644--- a/src/utils/responder-deployment.ts+++ b/src/utils/responder-deployment.ts@@ -1,5 +1,6 @@import type { RecommendedAutomation } from "@openhands/extensions/automations";import { I18nKey } from "#/i18n/declaration";+import { getRequiredIntegrationIds } from "#/utils/automation-catalog";import { PRODUCT_URL } from "#/utils/constants";/** OpenHands Cloud integrations page — where always-on responders are set up. */@@ -15,12 +16,14 @@ const RESPONDER_INTEGRATION_IDS = ["github", "slack"];/*** Single source of truth for "does this automation get the deployment-choice- * modal?" — true only for pure GitHub/Slack responders.+ * modal?" — true only for pure GitHub/Slack responders. An integration the+ * automation can start without does not decide where it runs, so only the+ * required ones are classified.*/export function isResponderAutomation(automation: RecommendedAutomation,): boolean {- const ids = automation.requiredIntegrationIds;+ const ids = getRequiredIntegrationIds(automation);return (ids.length > 0 && ids.every((id) => RESPONDER_INTEGRATION_IDS.includes(id)));