Deprecate tarball-based automation presets in favor of plugin-spec runners #612

Summary

Now that the plugin spec supports automations with both custom runners and a default runner, we should plan to deprecate tarball-based automation creation flows, including the prompt and plugin preset endpoints.

This issue tracks the migration from service-generated tarballs toward plugin-spec automation definitions as the primary contract.

Background

Today the Automation Service supports tarball-based automations through flows such as:

• POST /api/automation/v1/preset/prompt
• POST /api/automation/v1/preset/plugin
• uploaded/custom tarballs used by the raw automation creation path

The prompt and plugin preset endpoints generate or package code into tarballs, upload those tarballs, and dispatch them as sandbox workloads. That made sense before the plugin spec could directly describe automation execution. With the plugin spec now able to represent automation behavior through custom runners and a default runner, tarballs are no longer the ideal long-term API shape for prompt/plugin-style automations.

Why deprecate tarball-based presets

• The plugin spec becomes the single, reviewable source of truth for automation behavior.
• The default runner can cover common prompt/plugin automation cases without generated tarball boilerplate.
• Custom runners provide an explicit escape hatch for advanced execution logic.
• Automation definitions become easier to version, inspect, validate, and sync through catalog/git flows.
• The service can reduce duplicated packaging, upload, validation, and generated-code paths.
• Clients get a clearer product model: define an automation via plugin spec, then choose default or custom runner behavior.

Proposed direction

1. Treat plugin-spec automations as the preferred creation path.
2. Map existing prompt preset behavior onto the plugin spec default runner.
3. Map existing plugin preset behavior onto plugin spec automation definitions rather than service-generated tarballs.
4. Keep custom runner support for cases that previously required custom tarballs.
5. Mark tarball-based prompt and plugin endpoints as deprecated once equivalent plugin-spec paths are available.
6. Preserve existing tarball automations during a compatibility period, but stop recommending tarball presets for new usage.

Scope

Deprecation should include at least:

• POST /api/automation/v1/preset/prompt
• POST /api/automation/v1/preset/plugin
• Documentation and examples that recommend prompt/plugin tarball presets
• Capability metadata that currently presents tarball presets as the preferred path
• Catalog/bundle guidance that points new automations at tarball packaging when plugin-spec runners would work

This issue does not necessarily require immediately removing raw tarball upload support. Raw/custom tarballs may need a longer compatibility window or a separate deprecation plan because they can represent arbitrary workloads.

Suggested migration plan

Phase 1: Add the replacement path

• Add or document the plugin-spec automation creation API shape.
• Ensure prompt-like automations can run through the default runner.
• Ensure plugin-based automations can declare plugins, prompt/instructions, triggers, timeout, repositories, and relevant metadata without generated tarballs.
• Ensure custom runner definitions cover advanced use cases that previously required custom tarball contents.

Phase 2: Make the replacement visible

• Update capabilities/preflight responses to advertise plugin-spec automation support.
• Update docs and examples to recommend plugin-spec automation creation.
• Update catalog/template flows to emit plugin-spec automations where possible.
• Add migration guidance for existing prompt/plugin preset users.

Phase 3: Deprecate tarball preset endpoints

• Add deprecation notices to preset/prompt and preset/plugin responses, logs, or docs.
• Consider response headers such as Deprecation and Sunset once a timeline is chosen.
• Keep the endpoints functional during the compatibility window.
• Add telemetry to understand remaining usage before removal.

Phase 4: Remove or freeze legacy paths

• Stop adding new features to tarball-based prompt/plugin presets.
• Remove deprecated endpoints only after usage is low and migrations are available.
• Keep support for running existing automation records until an explicit data migration or end-of-life date.

Acceptance criteria

• A plugin-spec automation creation path exists for default-runner prompt-style automations.
• A plugin-spec automation creation path exists for plugin-based automations.
• Custom runners cover the main use cases that previously needed custom tarballs.
• Docs identify plugin-spec automations as the preferred path.
• preset/prompt and preset/plugin are documented as deprecated, with migration guidance.
• Capability/preflight responses let clients detect the new preferred path.
• Existing tarball-based automations continue to run during the compatibility period.
• Telemetry or logs can measure remaining usage of deprecated endpoints.

Open questions

• What is the exact API shape for creating plugin-spec automations in this service?
• Should raw custom tarball uploads be deprecated now, or only the prompt/plugin preset endpoints first?
• How long should the compatibility window be?
• Do existing automation records need a migration to plugin-spec form, or can legacy records remain as-is until edited/recreated?
• Should the UI hide tarball presets immediately after replacement paths ship, or show them as legacy/advanced options?

This issue was created by an AI agent (OpenHands) on behalf of the user.