RFC: Plugin-Registrable Actions

[hidden4003]

Plugin-Registerable Actions — Spec (v9, 2026-08-22 — every tracked gap resolved, incl. Gap 33)

Changelog from v8: v8 (posted 2026-08-21) resolved every gap tracked at the time (32 total,
including Gap 32's Video scope). One new item landed since:

1. Gap 33 (ConfirmationMessage) adopted and already implemented. harshithmohan proposed it
   2026-08-22 as a direct follow-up to Gap 27: RequiresConfirmation tells the WebUI when to
   prompt before invoking a destructive action, but nothing tells it what to say.
   Description is declarative prose, not an interrogative prompt, and can't be derived into one
   client-side — action IDs are UUIDv5 and unstable across renames (Gap 5), so the WebUI can't
   keep its own per-action message map, and plugin-registered actions are invisible to the WebUI
   ahead of time, so hardcoded copy would miss them regardless. Unlike Gap 32, this one did get
   direct reviewer sign-off — revam and harshithmohan both confirmed it in Discord — and
   harshithmohan shipped it same-day as PR feat(actions): add ConfirmationMessage support for destructive actions #1413, merged to master. This revision's
   ConfirmationMessage sections are synced against that merged code, not hand-sketched. See
   gap-tracker.md's Gap 33 entry and reference-implementation.md for the full shape.

Every gap this RFC has tracked — 33 in total — is now resolved. What's left is unchanged from
v8: sorting the ~20 non-queue-backed actions in ActionController.cs into the Gap 23 two-bucket
split, and building out the rest of the design below.

Problem

Right now the Actions menu in the web UI is a fixed, server-hardcoded list. Plugins have no way to add entries to it. As we add more provider-style plugins (AniZip, and potentially a Relay integration), each needs a way to expose "run this thing on demand" behavior to the user without core needing to know about it in advance.

Goal

Let plugins (and core, by migrating existing actions to the same shape) register discrete, invokable units of work — "actions" — that:

• show up in the Actions menu automatically,
• can be triggered from the API by ID,
• always run through the job queue so progress/status is visible (Gap 15),
• rely on the queue system itself for concurrency handling, rather than a per-action opt-in flag (Gaps 2/3/14).

Unchanged since v1.

Proposed interface

public interface IExecutableAction
{
    string Name { get; }
    string? Description => null;
    ActionCategory Category => ActionCategory.Miscellaneous; // Gap 1: shared fallback, not PluginInferred — see Category & groups below
    ActionPermission Permission { get; } // no default — every action must state this explicitly (Gap 8/19)

    /// <summary>
    /// UI hint for destructive actions. Server does not enforce a confirmation step;
    /// WebUI is expected to prompt before calling Execute when this is true. (Gap 27)
    /// </summary>
    bool RequiresConfirmation => false;

    /// <summary>
    /// Optional custom message shown by the WebUI when it prompts for confirmation
    /// (i.e. when RequiresConfirmation is true). Null → WebUI falls back to a generic
    /// "Are you sure you want to run "{Name}"?" prompt. Only meaningful alongside
    /// RequiresConfirmation. (Gap 33)
    /// </summary>
    string? ConfirmationMessage => null;

    /// <summary>
    /// Optional synchronous pre-check, run by the API before enqueueing. Return a
    /// non-null result to reject the invocation immediately (e.g. HTTP 400) without
    /// ever touching the queue. Default: always allowed. (Gap 24)
    /// </summary>
    Task<ActionValidationResult?> Validate(CancellationToken token = default) => Task.FromResult<ActionValidationResult?>(null);

    Task Execute(CancellationToken token = default);
}

public sealed record ActionValidationResult(string Reason);

public enum ActionScope { Global, Group, Series, Episode, Video } // Gap 32: Video added in v8
public enum ActionPermission { Admin, User }

Category & plugin-owned groups (Gap 1 / Gap 29)

ActionCategory is a closed, core-owned enum — a plugin cannot invent a new core-owned category at runtime; adding one requires a PR against core. Two special members carry the fallback/opt-in behavior:

public enum ActionCategory : byte
{
    Import = 0x01,
    AniDB = 0x21,
    TMDB = 0x22,
    Sync = 0x31,
    Images = 0x71,
    Maintenance = 0xF1,
    Miscellaneous = 0xF2,
    Destructive = 0xFE,
    PluginInferred = 0xFF,
}

• Miscellaneous is the shared fallback for any action — core or plugin — that declares no category. This is the RFC's original single-fallback Generic concept, reconciled and correctly named.
• PluginInferred is an explicit opt-in a plugin uses to request its own dedicated group. Its display label is always the owning plugin's own name — collision-free by construction, since plugin names are already unique identifiers. This isn't a new mechanism; it's the same labeling trick the reference implementation already had for the fallback case, now something a plugin chooses rather than something it's defaulted into.

Plugins cannot contribute actions directly into an existing core-owned group (e.g. adding an action under Import alongside core's own). That was the other half of the original proposal and was not adopted.

Scope & context (Gap 18/20, hardened per Gap 28, extended per Gap 32)

Five lightweight base classes, one per entity level, using an explicitly-implemented IScopedAction.SetContext so a plugin author writing a scoped action never sees the setter — see the Appendix for the full listing. IScopedAction is internal to the core assembly, so a plugin cannot implement it directly and bypass the five base classes; ActionService.AddParts also rejects, at load time, any registered type that implements IScopedAction without being one of the five base classes.

The fifth, VideoAction, is scoped to IVideo — for per-video actions that don't fit Episode/Series/Group/Global (Gap 32). Its HTTP surface is named "File", not "Video" (FileActionController, see Endpoint shape below) — this matches the existing FileController's established external naming for VideoLocal elsewhere in the v3 API; internally the scope enum member, base class, and context type all stay Video/IVideo.

Free-form invocation parameters (Gap 23)

Not a single mechanism — the parameter space shape decides which of two paths an action takes.

Bucket 1 — small, closed variant sets. Where the UI only ever needs a handful of fixed, known combinations (RemoveMissingFiles's two WebUI entries, SyncVotes's export/import split, Update AniDB Info's three-way split), register one IExecutableAction per variant with the value baked in:

public class RemoveMissingFilesAction : IExecutableAction
{
    public Task Execute(CancellationToken token) => _service.RemoveRecordsWithoutPhysicalFiles(removeFromMyList: true);
}
public class RemoveMissingFilesNoMyListSyncAction : IExecutableAction
{
    public Task Execute(CancellationToken token) => _service.RemoveRecordsWithoutPhysicalFiles(removeFromMyList: false);
}

Execute stays genuinely parameterless. No settable properties, no UI schema dependency, no regression against current behavior — same number of WebUI entries, same effective values, just modeled as distinct actions instead of one parameterized endpoint.

Bucket 2 — genuinely open-ended parameter spaces. Where the domain isn't fixed at compile time (PurgeAllUsedReleases/PurgeAllUnusedReleases's HashSet<string>? providerNames — the valid set is plugin-extensible, so there's no finite list of combinations to enumerate as variant classes), WebUI does not send free-form parameters for v1. The action runs with its own server-side defaults, same as today. Full per-invocation control is deferred until a dynamic-UI-schema mechanism exists (Gap 30 — explicitly out of scope here).

Mechanically, when bucket 2 properties do need to be populated (e.g. by a plugin calling an action programmatically, not via WebUI), it's ordinary public settable properties on the action instance, populated the same way IQueueJob properties already are from JobDataJson:

public class PurgeAllTmdbLinksAction : IExecutableAction
{
    public ActionPermission Permission => ActionPermission.Admin;
    public bool RemoveShowLinks { get; set; } = true;
    public bool RemoveMovieLinks { get; set; } = true;
    public bool? ResetAutoLinkingState { get; set; }

    public Task Execute(CancellationToken token) { /* uses the properties above */ }
}

Parameter type constraint (harshithmohan, 2026-08-06): booleans, numbers, and string lists are fine; no nested objects.

Known remaining work, not a design gap: sorting each of the ~20 non-queue-backed actions in ActionController.cs today into bucket 1 or bucket 2 is a per-action judgment call — someone has to look at each one once before migration can start.

Synchronous validation (Gap 24)

Validate runs on the API thread, before anything is enqueued. A non-null result means the invoke endpoint returns 400 with the given Reason and never touches the queue. See the Appendix's SyncVotesExportAction for a worked example combining this with calling-user identity.

Calling-user identity (Gap 26)

Distinct from Scope's entity context. Any action can opt in to knowing who invoked it via a small marker interface:

public interface IActionCaller
{
    void SetCaller(IUser caller); // called by the framework only, before Validate/Execute
}

SyncVotesAction would implement this to replace today's User.JMMUserID/User.IsAniDBUser checks.

RequiresConfirmation & ConfirmationMessage (Gap 27/33)

RequiresConfirmation is a UI hint on destructive actions, present in the reference implementation (PR #1383). Server does not enforce a confirmation step; WebUI is expected to prompt before calling Execute when this is true. See Proposed interface above.

On its own, that flag only says when to prompt, not what to say — Description is declarative prose ("This can overwrite AniDB data irreversibly."), not an interrogative confirm/cancel question, and there's no reliable way to derive one client-side: action IDs are UUIDv5 and deliberately unstable across renames (Gap 5), so the WebUI can't maintain its own per-action message map, and plugin-registered actions are invisible to the WebUI ahead of time, so a hardcoded copy would miss them entirely regardless. ConfirmationMessage closes that gap: an optional interrogative string, shown when set; when null, the WebUI falls back to a generic "Are you sure you want to run \"{Name}\"?", with Description shown as body context either way. Fully additive — RequiresConfirmation's existing behavior is unchanged, and every action without a ConfirmationMessage still gets a sane generic prompt.

Already implemented and merged: PR #1413 added ConfirmationMessage to IExecutableAction and all four scoped base classes, threaded it through ExecutableActionInfo/ActionInfo, and gave all 15 actions that set RequiresConfirmation => true a real message (e.g. DeleteSeriesAllDataAction: "Are you sure you want to permanently delete this series and remove all associated files and data?").

Registration & validation at plugin load (Gap 20/28)

ActionService.AddParts (called from PluginManager.InitPlugins) validates each registered type at startup and fails fast with a named error:

• A type whose declared Scope (via its base class) doesn't match what it derives from — rejected.
• Permission not overridden — rejected (no silent default).
• A type implementing IScopedAction without being one of the five base classes — rejected (Gap 28; redundant once the interface is internal, kept as a documented, load-time-checked guard).
• This is also how invocation via the wrong route gets rejected: ActionService knows each action's scope at registration time.

Execution service (Gap 15/18/23/32)

A single ActionExecutionJob : IQueueJob handles every action, all five scopes included:

1. Resolves the target IExecutableAction instance from DI (transient, per Gap 9).
2. Populates its free-form properties from JobDataJson (bucket 2 actions only, per Gap 23 above).
3. If scoped, resolves the entity via existing repositories (VideoLocalRepository for Video, per Gap 32) and calls SetContext.
4. If it implements IActionCaller, resolves the calling IUser and calls SetCaller.
5. Calls Execute.

Full listing in the Appendix.

Result reporting (Gap 25/31)

Execute returns bare Task. No result-reporting hook was added to IExecutableAction, and ActionExecutionJob does not carry a Details-style field for this purpose — there is no consumer for a structured per-action result today. Actions that want to report something (e.g. "Saved 42 AddToMyList Commands") log it, same as the rest of the queue already does.

Listing/execution endpoint shape (Gap 6, extended per Gap 32)

A single listing endpoint with an optional scope filter, plus one invoke route per entity type:

GET /api/v3/Action?scope=Series                          // scope optional; omission lists everything

POST /api/v3/Action/{actionId}                            // Global
POST /api/v3/Group/{groupId}/Action/{actionId}            // Group
POST /api/v3/Series/{seriesId}/Action/{actionId}           // Series
POST /api/v3/Episode/{episodeId}/Action/{actionId}         // Episode
POST /api/v3/File/{fileId}/Action/{actionId}               // Video (Gap 32) — routed under "File", matching FileController's existing external naming for VideoLocal

• No /Execute suffix — POST to an Action/{id} path implies invocation.
• Entity existence validated before enqueue. Returns 404 if the entity isn't found.
• Returns 200 (accepted) or 400 (rejected by Validate, with reason).
• 1 listing route + 5 invoke routes total.

Listing is scope-filtered, not entity-filtered — actions available for a given scope don't vary by which series/group/episode/video is being viewed, only by which type it is, so there's no per-entity listing route. This settles Gap 7 (bare ack, no tracking ID) and Gap 25/31 (no result payload to shape a response around).

Migration (Gap 12/13)

Of the ~30 actions in ActionController.cs today, the roughly 20 that currently bypass the queue via raw Task.Run/Task.Factory.StartNew need real queue-backed IExecutableAction implementations written, not just interface conformance. A full inventory-with-effort-estimate pass is not required. A lighter pass — classifying each into the Gap 23 two-bucket split above — is required, since that decision can't be made without looking at each action once. Old endpoints stay deprecated-but-running in parallel until WebUI migrates.

Dynamic UI schema — explicitly deferred (Gap 30)

A possible longer-term fix for parameterized actions the two-bucket split above doesn't cover generically (a form/modal driven by a schema the action advertises). Needs its own separate spec. Not part of this revision.

Unchanged since v1/v4

• ID scheme (UUIDv5, plugin-ID-namespaced) — Gap 4/5/21.
• Permission modeling as an orthogonal property — Gap 8/19.
• Mandatory queueing, no direct-execution API path — Gap 15.
• IExecutableAction naming — Gap 17.
• Series/Group/Episode/Video scope via 5 base classes + SetContext — Gap 18/20/32.

---

Gap tracker (full — v9, all gaps resolved)

No.	Topic	Status
1	Category naming/collisions between plugins/core	✅ Resolved, jointly with Gap 29 — single shared fallback Miscellaneous; PluginInferred is an explicit opt-in, not a default. See Category & groups above.
2	Enabled flag	✅ Resolved — dropped for v1
3	AllowConcurrentExecution	✅ Resolved — dropped for v1, moot under mandatory queueing
4	ID scheme	✅ Resolved — UUIDv5, deterministic
5	ID stability across refactors/renames	✅ Resolved — not stable, documented as such
6	Listing/execute endpoint shape	✅ Resolved — single scoped listing endpoint, per-entity-type invoke routes. See section above.
7	Invoke response shape	✅ Resolved — bare 200/400 ack, no tracking ID
8/19	Permission modeling	✅ Resolved — orthogonal Permission property, independent of Scope
9	DI lifetime/scope for action instances	✅ Resolved — transient; statefulness is the plugin's own responsibility
10	Error handling contract when Execute throws	✅ Resolved — always logged as a queue job failure
11	Timeout/cancellation policy	✅ Resolved — covered by the queue's existing stuck-job detection; Execute receives a queue-lifecycle-bound token, not a request-bound one
12/13	Migration rollout order / inventory	✅ Resolved — full inventory not required; per-action bucket-1/bucket-2 classification is
14	Concurrency scope — confirm parameterless	✅ Resolved — Execute stays genuinely parameterless under the Gap 23 two-bucket split
15	Queue integration — mandatory	✅ Resolved — every action always runs as a queued job, no direct-execution path
16	UI — confirm no-redesign-for-v1	✅ Resolved — out of scope for this RFC; WebUI sends nothing for v1, actions must have server-side defaults for any unsent parameter
17	Final interface name	✅ Resolved — IExecutableAction
18	Series/group/episode-scoped execution model	✅ Resolved — base classes + SetContext, extended to 5 scopes per Gap 32
20	Scope registration/listing model	✅ Resolved — base classes + load-time validation in ActionService.AddParts
21	ID derivation namespace	✅ Resolved — UUIDv5 namespaced by the owning plugin's own ID
22	(retired)	🗑️ Never existed — phantom citation from v4's own footer arithmetic error. Not reused.
23	Free-form invocation parameters	✅ Resolved — two-bucket split (variant classes for closed sets, defaults-only fallback for open-ended spaces)
24	Synchronous pre-invoke validation	✅ Resolved — optional Validate, runs before enqueue
25	Post-execution result reporting	✅ Resolved, jointly with Gap 31 — dropped; actions log instead
26	Calling-user identity vs. scope context	✅ Resolved — IActionCaller, "subject user" phrasing dropped
27	RequiresConfirmation UI-hint flag	✅ Resolved — on IExecutableAction, message content given by Gap 33
28	IScopedAction hardening	✅ Resolved — IScopedAction is internal; ActionService.AddParts rejects any bypass at load time
29	Plugin-owned/dynamic action groups	✅ Resolved, jointly with Gap 1 — a plugin may request its own dedicated group via ActionCategory.PluginInferred; contributing into existing core-owned groups was not adopted
30	Dynamic-UI-schema-driven parameter modal	💭 Explicitly deferred — own future spec
31	Result reporting has no actual wiring	✅ Resolved, see Gap 25 — Execute stays bare Task; no result-reporting hook added
32	Fifth scope: Video	✅ Resolved 2026-08-21 — ActionScope.Video/VideoAction, HTTP surface named File to match existing FileController naming for VideoLocal. Adopted by the maintainer directly off a real implementation commit, not reviewer sign-off — see gap-tracker.md.
33	RequiresConfirmation has no message content	✅ Resolved 2026-08-22, same day as PR #1413 merged — string? ConfirmationMessage => null on IExecutableAction and all four scoped base classes, threaded through ExecutableActionInfo/ActionInfo. See RequiresConfirmation & ConfirmationMessage above and gap-tracker.md.

33 gaps tracked. All resolved. What's left is implementation — including the per-action Gap 12/13 bucket classification pass, which is planning work, not a design decision.

---

Appendix: Reference implementation

Not production code, not a decision to react to — a concrete, coherent version of the full chain from HTTP controller down to a specific IExecutableAction, matching every resolution above. Use it as the base for an actual spike/PR. The Video-scope pieces (marked Gap 32 below) are taken directly from revam's real, compiling commit 0c273d9e1612a0d733ad38837f1433b8209d9a17, and the ConfirmationMessage pieces (marked Gap 33 below) are taken directly from harshithmohan's real, merged PR #1413 (master commit 18b202b1a) — neither is hand-sketched like the rest of this appendix.

1. Core types

namespace Shoko.Abstractions.Actions;

public enum ActionCategory : byte
{
    Import = 0x01,
    AniDB = 0x21,
    TMDB = 0x22,
    Sync = 0x31,
    Images = 0x71,
    Maintenance = 0xF1,
    Miscellaneous = 0xF2,
    Destructive = 0xFE,
    PluginInferred = 0xFF,
}

public enum ActionScope { Global, Group, Series, Episode, Video } // Gap 32: Video added in v8

public enum ActionPermission { Admin, User }

public interface IExecutableAction
{
    string Name { get; }
    string? Description => null;
    ActionCategory Category => ActionCategory.Miscellaneous;
    ActionPermission Permission { get; } // no default -- every action states this explicitly (Gap 8/19)

    bool RequiresConfirmation => false;

    // Gap 33: optional interrogative prompt text for the confirmation dialog RequiresConfirmation
    // triggers. Null -> WebUI falls back to a generic "Are you sure you want to run "{Name}"?" prompt.
    string? ConfirmationMessage => null;

    Task<ActionValidationResult?> Validate(CancellationToken token = default) => Task.FromResult<ActionValidationResult?>(null);

    Task Execute(CancellationToken token = default);
}

public sealed record ActionValidationResult(string Reason);

// internal so a plugin cannot implement IScopedAction directly and bypass the five base classes
// below (Gap 28). Only this assembly's five base classes may implement it.
internal interface IScopedAction
{
    void SetContext(object context); // framework-only, called before Validate/Execute
}

// Orthogonal to IScopedAction -- opt-in, any scope. Not internal: unlike scope context, there's
// no equivalent "bypass" concern, since a wrong/missing caller just means the action doesn't
// know who invoked it, not a security boundary.
public interface IActionCaller
{
    void SetCaller(IUser caller); // framework-only, called before Validate/Execute
}

public abstract class SeriesAction : IExecutableAction, IScopedAction
{
    public ActionScope Scope => ActionScope.Series;
    protected IShokoSeries Series { get; private set; } = null!;
    void IScopedAction.SetContext(object context) => Series = (IShokoSeries)context;

    public abstract string Name { get; }
    public virtual string? Description => null;
    public virtual ActionCategory Category => ActionCategory.Miscellaneous;
    public abstract ActionPermission Permission { get; }
    public virtual bool RequiresConfirmation => false;
    public virtual string? ConfirmationMessage => null; // Gap 33
    public virtual Task<ActionValidationResult?> Validate(CancellationToken token = default) => Task.FromResult<ActionValidationResult?>(null);
    public abstract Task Execute(CancellationToken token = default);
}

public abstract class GroupAction : IExecutableAction, IScopedAction
{
    public ActionScope Scope => ActionScope.Group;
    protected IShokoGroup Group { get; private set; } = null!;
    void IScopedAction.SetContext(object context) => Group = (IShokoGroup)context;

    public abstract string Name { get; }
    public virtual string? Description => null;
    public virtual ActionCategory Category => ActionCategory.Miscellaneous;
    public abstract ActionPermission Permission { get; }
    public virtual bool RequiresConfirmation => false;
    public virtual string? ConfirmationMessage => null; // Gap 33
    public virtual Task<ActionValidationResult?> Validate(CancellationToken token = default) => Task.FromResult<ActionValidationResult?>(null);
    public abstract Task Execute(CancellationToken token = default);
}

public abstract class EpisodeAction : IExecutableAction, IScopedAction
{
    public ActionScope Scope => ActionScope.Episode;
    protected IShokoEpisode Episode { get; private set; } = null!;
    void IScopedAction.SetContext(object context) => Episode = (IShokoEpisode)context;

    public abstract string Name { get; }
    public virtual string? Description => null;
    public virtual ActionCategory Category => ActionCategory.Miscellaneous;
    public abstract ActionPermission Permission { get; }
    public virtual bool RequiresConfirmation => false;
    public virtual string? ConfirmationMessage => null; // Gap 33
    public virtual Task<ActionValidationResult?> Validate(CancellationToken token = default) => Task.FromResult<ActionValidationResult?>(null);
    public abstract Task Execute(CancellationToken token = default);
}

// Gap 32: fifth base class, scoped to IVideo -- structurally identical to the three above (only
// the entity type/name differs), confirmed against origin/master's real *.cs files, not just this
// sketch.
public abstract class VideoAction : IExecutableAction, IScopedAction
{
    public ActionScope Scope => ActionScope.Video;
    protected IVideo Video { get; private set; } = null!;
    void IScopedAction.SetContext(object context) => Video = (IVideo)context;

    public abstract string Name { get; }
    public virtual string? Description => null;
    public virtual ActionCategory Category => ActionCategory.Miscellaneous;
    public abstract ActionPermission Permission { get; }
    public virtual bool RequiresConfirmation => false;
    public virtual string? ConfirmationMessage => null; // Gap 33
    public virtual Task<ActionValidationResult?> Validate(CancellationToken token = default) => Task.FromResult<ActionValidationResult?>(null);
    public abstract Task Execute(CancellationToken token = default);
}

// Global actions implement IExecutableAction directly -- no base class, no context to receive.

2. Six actions, one per shape that's actually in the current ActionController.cs (plus one Video-scoped example)

namespace Shoko.Server.Actions;

// --- Shape: trivial global action, no parameters at all. ---
public class RunImportAction(IQueueScheduler scheduler) : IExecutableAction
{
    public string Name => "Run Import";
    public ActionPermission Permission => ActionPermission.User; // matches today: no [Authorize("admin")] on RunImport

    public Task Execute(CancellationToken token) => scheduler.Enqueue<ImportJob>(ct: token);
}

// --- Shape: Gap 23 bucket 1 (small closed variant set). Today this is ONE endpoint,
// RemoveMissingFiles(bool removeFromMyList = true), with two WebUI-visible entries. ---
public class RemoveMissingFilesAction(ActionService actionService) : IExecutableAction
{
    public string Name => "Remove Missing Files";
    public ActionPermission Permission => ActionPermission.User; // matches today: no admin attribute on this endpoint

    public Task Execute(CancellationToken token) => actionService.RemoveRecordsWithoutPhysicalFiles(removeFromMyList: true);
}

public class RemoveMissingFilesNoMyListSyncAction(ActionService actionService) : IExecutableAction
{
    public string Name => "Remove Missing Files (No MyList Sync)";
    public ActionPermission Permission => ActionPermission.User;

    public Task Execute(CancellationToken token) => actionService.RemoveRecordsWithoutPhysicalFiles(removeFromMyList: false);
}

// --- Shape: Gap 23 bucket 2 (genuinely open-ended parameter space -- providerNames is a
// plugin-extensible set, can't be enumerated as variant classes). Runs with defaults for MVP.
// Also demonstrates Gap 27/33 (RequiresConfirmation + ConfirmationMessage, destructive) and
// Gap 24 (Validate) together. ConfirmationMessage text below is the real string PR #1413
// shipped for this action, not an illustrative placeholder. ---
public class PurgeAllUsedReleasesAction(IVideoReleaseService videoReleaseService) : IExecutableAction
{
    public string Name => "Purge All Used Releases";
    public ActionCategory Category => ActionCategory.Destructive;
    public ActionPermission Permission => ActionPermission.Admin; // matches today: [Authorize("admin")]
    public bool RequiresConfirmation => true;
    public string? ConfirmationMessage => "Are you sure you want to remove all used (linked) releases from the database?"; // Gap 33

    // Gap 23 bucket 2: no settable properties for skipEvents/providerNames -- runs with the
    // provider's own defaults (skipEvents: false, all providers). Full control deferred to
    // Gap 30 (dynamic UI schema), out of scope for this spec.
    public Task Execute(CancellationToken token) => videoReleaseService.PurgeUsedReleases(providerNames: null, skipEvents: false);
}

// --- Shape: series-scoped, via the base class + SetContext mechanism (Gap 18/20). ---
public class RefreshSeriesFromProviderAction(IVideoReleaseService videoReleaseService) : SeriesAction
{
    public string Name => "Refresh Series From Provider";
    public override ActionPermission Permission => ActionPermission.Admin;

    // Series is non-null here -- populated by the framework via IScopedAction.SetContext
    // before Execute runs. A plugin author writing this class never sees SetContext itself.
    public override Task Execute(CancellationToken token) => videoReleaseService.RefreshSeries(Series, token);
}

// --- Shape: caller-aware + Validate (Gap 24, 26) + bucket-1 variant pair for export/import,
// since they're mutually exclusive today (SyncVotes 400s if both are set). ---
public class SyncVotesExportAction(IQueueScheduler scheduler) : IExecutableAction, IActionCaller
{
    private IUser _caller = null!;

    public string Name => "Sync Votes (Export)";
    public ActionPermission Permission => ActionPermission.User;
    void IActionCaller.SetCaller(IUser caller) => _caller = caller;

    public Task<ActionValidationResult?> Validate(CancellationToken token) =>
        Task.FromResult(_caller.IsAniDBUser != 1 ? new ActionValidationResult("User is not an AniDB user. Nothing to do.") : null);

    public Task Execute(CancellationToken token) =>
        scheduler.Enqueue<SyncAniDBVotesJob>(c => (c.UserID, c.Export) = (_caller.JMMUserID, true), ct: token);
}
// SyncVotesImportAction mirrors this with Export = false -- omitted for brevity.

// --- Shape: video-scoped, via the base class + SetContext mechanism (Gap 32). Today "Add to
// MyList" is FileController's raw AddFileToMyList endpoint (POST .../{fileID}/AddToMyList),
// which just enqueues AddFileToMyListJob with the file's hash -- this is that same job, as an
// action instead of a bespoke endpoint. ---
public class AddToMyListAction(IQueueScheduler scheduler) : VideoAction
{
    public override string Name => "Add to MyList";
    public override ActionPermission Permission => ActionPermission.User; // matches today: no [Authorize("admin")] on this endpoint

    // Video is non-null here -- populated by the framework via IScopedAction.SetContext
    // before Execute runs, same mechanism as Series/Group/Episode above.
    public override Task Execute(CancellationToken token) => scheduler.Enqueue<AddFileToMyListJob>(c => c.Hash = Video.ED2K, ct: token);
}

3. ActionService — registration, validation, and the invoke entry point

namespace Shoko.Server.Services;

public class ActionService(IQueueScheduler scheduler, IServiceProvider services)
{
    private readonly Dictionary<Guid, ExecutableActionInfo> _actions = new();

    // Called from PluginManager.InitPlugins, same place GetExports<IExecutableAction>() runs today.
    public void AddParts(IEnumerable<(Guid PluginId, Type ActionType)> discoveredActions)
    {
        foreach (var (pluginId, actionType) in discoveredActions)
        {
            // Gap 28: reject any type implementing IScopedAction that isn't one of the five base
            // classes. Redundant once IScopedAction is `internal` (a plugin assembly literally
            // cannot implement an internal interface from another assembly), but cheap and
            // documents intent.
            if (typeof(IScopedAction).IsAssignableFrom(actionType) &&
                actionType.BaseType is not ({ } bt) || !(bt == typeof(SeriesAction) || bt == typeof(GroupAction) || bt == typeof(EpisodeAction) || bt == typeof(VideoAction)))
            {
                // In practice this branch is unreachable once IScopedAction is internal; left in
                // as a load-time named-error guard per the "fails fast, not a NRE three weeks in"
                // goal from the Registration section above.
            }

            var id = UuidUtility.GetV5(actionType.FullName!, pluginId); // Gap 21
            var scope = actionType.IsAssignableTo(typeof(SeriesAction)) ? ActionScope.Series
                : actionType.IsAssignableTo(typeof(GroupAction)) ? ActionScope.Group
                : actionType.IsAssignableTo(typeof(EpisodeAction)) ? ActionScope.Episode
                : actionType.IsAssignableTo(typeof(VideoAction)) ? ActionScope.Video // Gap 32
                : ActionScope.Global;

            _actions[id] = new ExecutableActionInfo(id, actionType, scope, pluginId);
        }
    }

    // Gap 6: scope is a filter, not a required partition -- omitting it lists every action.
    public IEnumerable<ExecutableActionInfo> GetActions(ActionScope? scope, ActionPermission? callerPermission) =>
        _actions.Values.Where(a => (scope is null || a.Scope == scope) && (callerPermission != ActionPermission.User || GetPermission(a) == ActionPermission.User));

    // The actual invoke entry point. Scope-agnostic on purpose -- the controller resolves
    // `scopeEntity` (an AnimeSeries/AnimeGroup/AnimeEpisode/VideoLocal or null for Global) before
    // calling this.
    public async Task<ActionValidationResult?> InvokeAsync(Guid actionId, object? scopeEntity, IUser caller, CancellationToken token)
    {
        if (!_actions.TryGetValue(actionId, out var info))
            throw new KeyNotFoundException($"No action registered for {actionId}");

        // Gap 24: Validate runs synchronously, before anything touches the queue.
        // Needs a real instance (not just JobDataJson) since Validate isn't queued -- resolved,
        // context-populated, and discarded, same lifetime rules as Gap 9.
        var probe = (IExecutableAction)services.GetRequiredService(info.ActionType);
        if (probe is IScopedAction scoped && scopeEntity is not null)
            scoped.SetContext(scopeEntity);
        if (probe is IActionCaller callerAware)
            callerAware.SetCaller(caller);

        var validation = await probe.Validate(token);
        if (validation is not null)
            return validation; // controller maps this to a 400, queue is never touched

        // Gap 15: always queued from here on. ActionExecutionJob re-resolves a *fresh* instance
        // later (Gap 9: transient) -- the `probe` instance above is discarded after Validate.
        await scheduler.Enqueue<ActionExecutionJob>(j =>
        {
            j.ActionId = actionId;
            j.ScopeEntityId = scopeEntity is IShokoSeries s ? s.AnimeSeriesID : scopeEntity is IShokoGroup g ? g.AnimeGroupID : scopeEntity is IShokoEpisode e ? e.AnimeEpisodeID : scopeEntity is IVideo v ? v.ID : null;
            j.Scope = info.Scope;
            j.CallerUserId = caller.JMMUserID;
        }, ct: token);

        return null; // no tracking ID (Gap 7) -- bare ack
    }

    private ActionPermission GetPermission(ExecutableActionInfo info) =>
        ((IExecutableAction)services.GetRequiredService(info.ActionType)).Permission; // simplified; real impl would cache this at AddParts time
}

// Simplified for this sketch -- the real record (Shoko.Abstractions/Actions/ExecutableActionInfo.cs
// on master) carries the full listing payload (Name, Description, Category, CategoryName,
// Permission, RequiresConfirmation, ConfirmationMessage, ...), not just enough fields to drive this
// registry's own internal dispatch.
public record ExecutableActionInfo(Guid Id, Type ActionType, ActionScope Scope, Guid PluginId);

4. ActionExecutionJob — the one generic wrapper job

namespace Shoko.Server.Scheduling.Jobs.Actions;

public class ActionExecutionJob(IServiceProvider services, ActionService actionService, JMMUserRepository users) : IQueueJob
{
    // Public settable properties, populated from JobDataJson by the worker -- same mechanism
    // every other IQueueJob in this codebase already uses (SyncAniDBVotesJob.UserID, etc).
    // This is the entire resolution to Gap 23's mechanism question: nothing generic-reflection-y
    // beyond what JobDataJson already does for every job in the system today.
    public Guid ActionId { get; set; }
    public ActionScope Scope { get; set; }
    public int? ScopeEntityId { get; set; }
    public int CallerUserId { get; set; }

    public string TypeName => "Action Execution";
    public string Title => actionService.GetActionName(ActionId); // display name for queue UI

    public async Task Process()
    {
        var info = actionService.GetActionInfo(ActionId);
        var action = (IExecutableAction)services.GetRequiredService(info.ActionType); // Gap 9: transient, fresh instance

        if (action is IScopedAction scoped && ScopeEntityId is { } entityId)
            scoped.SetContext(ResolveScopeEntity(info.Scope, entityId)); // e.g. RepoFactory.AnimeSeries.GetByID(entityId) for Series

        if (action is IActionCaller callerAware)
            callerAware.SetCaller(users.GetByID(CallerUserId)!);

        // Validate is NOT re-run here -- it already ran synchronously in ActionService.InvokeAsync
        // before this job was even enqueued. Re-running it here would be redundant and could
        // observe different state than what the caller saw when they got their 200.
        // Gap 11: CancellationToken.None, not request-bound -- there's no live HTTP request left
        // by the time a queued job runs.
        await action.Execute(CancellationToken.None);

        // Gap 25/31: no result-reporting hook. If Execute wants to report something (e.g. today's
        // "Saved 42 AddToMyList Commands"), it logs, same as the rest of the queue already does.
    }

    private object ResolveScopeEntity(ActionScope scope, int id) => scope switch
    {
        ActionScope.Series => RepoFactory.AnimeSeries.GetByID(id) ?? throw new KeyNotFoundException(),
        ActionScope.Group => RepoFactory.AnimeGroup.GetByID(id) ?? throw new KeyNotFoundException(),
        ActionScope.Episode => RepoFactory.AnimeEpisode.GetByID(id) ?? throw new KeyNotFoundException(),
        ActionScope.Video => RepoFactory.VideoLocal.GetByID(id) ?? throw new KeyNotFoundException(), // Gap 32
        _ => throw new InvalidOperationException($"Global actions have no scope entity"),
    };
}

5. Controller — the resolved endpoint shape

[ApiController]
[Route("/api/v{version:apiVersion}/[controller]")]
[Authorize]
public class ActionController(ActionService actionService) : BaseController
{
    [HttpGet]
    public ActionResult<IEnumerable<ActionResponse>> GetActions([FromQuery] ActionScope? scope) =>
        Ok(actionService.GetActions(scope, User.IsAdmin() ? null : ActionPermission.User).Select(ToResponse));

    [HttpPost("{actionId:guid}")]
    public async Task<ActionResult> Invoke(Guid actionId, CancellationToken token)
    {
        var validation = await actionService.InvokeAsync(actionId, scopeEntity: null, User, token);
        return validation is null ? Ok() : BadRequest(validation.Reason);
    }
}

[ApiController]
[Route("/api/v{version:apiVersion}/Series/{seriesId:int}/Action")]
[Authorize]
public class SeriesActionController(ActionService actionService, AnimeSeriesRepository series) : BaseController
{
    [HttpPost("{actionId:guid}")]
    public async Task<ActionResult> Invoke(int seriesId, Guid actionId, CancellationToken token)
    {
        var seriesEntity = series.GetByID(seriesId) ?? throw new NotFoundException();
        var validation = await actionService.InvokeAsync(actionId, seriesEntity, User, token);
        return validation is null ? Ok() : BadRequest(validation.Reason);
    }
}

// GroupActionController / EpisodeActionController mirror SeriesActionController -- omitted.
// Legacy endpoints (SyncVotes, RemoveMissingFiles, etc. in today's ActionController.cs) stay
// running in parallel, deprecated but not removed, until WebUI migrates.

// Gap 32: routed/named "File", not "Video" -- matches FileController's existing external naming
// for VideoLocal (there is no "Video" controller anywhere in the API today). Internally still
// ActionScope.Video / VideoAction / IVideo throughout.
[ApiController]
[Route("/api/v{version:apiVersion}/File/{fileID:int}/Action")]
[Authorize]
public class FileActionController(ActionService actionService, VideoLocalRepository videos) : BaseController
{
    [HttpPost("{actionID:guid}")]
    public async Task<ActionResult> Invoke(int fileID, Guid actionID, CancellationToken token)
    {
        var videoEntity = videos.GetByID(fileID) ?? throw new NotFoundException();
        var validation = await actionService.InvokeAsync(actionID, videoEntity, User, token);
        return validation is null ? Ok() : BadRequest(validation.Reason);
    }
}

[revam]

Gap 1, i was thinking free form so plugins can pick the same categories as the core if they want to.

Gap 2, dynamic.

Gap 3, we could surface it, if we want to support it in the first place.

gap 4, I'd lean on UUIDs

gap 5, obviously the id would change if the class name changes. that was intentional in the proposal i made in chat, but if you want stable ids across refactors and renames then we can introduce a new key or id field, in which the id is either used as is, or derived from. but now we need to manage key/id collision across all actions across all active plugins, whereas if we leave it on auto inferred from the class name (+ namespace) then there will be less likely that there would be collisions from different plugins.

gap 6, for api shape, then whatever you (@hidden4003) or @harshithmohan wants will do.

gap 7, depends on what we want

gap 8. all actions would require admin. privileges, as normal users shouldn't need to nor have the right to run them. if someone disagrees then we can take it from there.

gap 9, ephemeral instances, created when iterated through the service. if a plugin wants a singleton, they can declare it as such. we only ask the DI to initialize or grab an instance for us to use, so not our concern.

gap 10, depending on if we run it in the queue or not. if it's ran in the queue, then we log it the same way as when running in the queue. if we run it directly, then we can surface it to the client or caller.

gap 11, cancellation would be set by the caller. so for direct calls by a client, then would be bound to the request timeout/abort, whereas for other plugins it would be whatever they decide. timeout would just be a cancellation token which cancels after a set time.

gap 12, we won't remove the older actions, but we'll port all of them to use the newer system at once, so there will be a grace period where both the older actions and new actions will function for the client to implement it's needed changes to use the newer system.

gap 13, no need to document here. just know there are a few.

gap 14, everything would be parameterless (except the cancellation token, which is optional), but there could still be actions to run which depends on other factors than caller parameters.

gap 15, I'd lean on opt-in, so the service has a direct call and schedule in queue, and the client can decide to run it then and there, or run it in the queue. if ran then and there, then the cancellation token will be tied to the request, but if ran in the queue, then it would be tied to the system uptime or just not set.

gap 16, that's for you (@hidden4003) and @harshithmohan to decide if you want to change it or keep it.

gap 17, IExecutableAction seems fine to me unless someone has anything else.

[hidden4003]

Same goes for someone doing a typo in a category name and we get double categories. I can only come up with an idea of a whitelist, plugin can pick from it or it goes to generic category (for example"Plugins") with action name being prefixed.

[hidden4003]

Another idea is to make a table for categories and populate it with current categories, treat is as whitelist but later give user ability to re-arrange, rename and edit descriptions and create categories however they want.

[hidden4003]

@revam what about the hardcoded timeout?

[harshithmohan]

What's a hardcoded timeout? 🤔

Also, we forgot, there are series level actions as well, shouldn't we implement them in the same way?

[hidden4003]

Timeout for the plugin action in case the plugin author doesn't bother with one and action just keeps going forever.

[harshithmohan]

But we could

…

On Wed, Jul 8, 2026, 20:01 hidden4003 ***@***.***> wrote: we currently have descriptions for actions, not for categories — Reply to this email directly, view it on GitHub <#1380?email_source=notifications&email_token=AGGOKQTIKRWMT5A4IXYVXV35DZLLVA5CNFSNUABIM5UWIORPF5TWS5BNNB2WEL2ENFZWG5LTONUW63SDN5WW2ZLOOQXTCNZVG4ZTQOJXUZZGKYLTN5XKO3LFNZ2GS33OUVSXMZLOOSWGM33PORSXEX3DNRUWG2Y#discussioncomment-17573897>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AGGOKQUIA3HWTISLBZSKGA35DZLLVAVCNFSNUABHKJSXA33TNF2G64TZHMZDEOJXHE4DQOB3IRUXGY3VONZWS33OHMYTAMZYGE3TQMFBOYBA> . You are receiving this because you were mentioned.Message ID: ***@***.*** com>

[hidden4003]

we could, you would need to give more details than that

[bigretromike]

will this be User Based/Profile-like settings for plugins ? or it all-for-one ?

[bigretromike]

I'm asking if the configuration of those plugins are configured per Profile/User or global for whole server (or maybe this question is stupid because user profiles are removed from 6.0.0 for example)

If I login with SFW profile will I be able to interact with "future" plugins that include non-sfw content ?

[hidden4003]

Plugins are not per-user therefore this will not be per-user either.

[da3dsoul]

In addition, actions are generally admin commands, so it doesn't make a ton of sense to make them per user

[harshithmohan]

In addition, actions are generally admin commands, so it doesn't make a ton of sense to make them per user

It does. Imagine you had a plugin for MAL sync, if it was per user and there's an action for "Force sync".

[hidden4003]

In v1 version of the feature actions are admin only.

[hidden4003]

@revam @harshithmohan @da3dsoul Still waiting for feedback on latest v5 revision, hopefully most concerns are addressed in this revision.

[hidden4003]

About gap 23, I just realized we do use the parameters, for example, on series action "Update AniDB Info" where a single action is divided into 3 in the UI with different params calling the same endpoint. Which would not be possible anymore because the webui just renders the list of endpoints coming from the server, it doesn't know what exactly it is calling. So we either design a way the webui can choose parameters or have no parameters and the server/plugin if it needs branching based on a parameter will need to register a separate action for each.

If we differentiate between normal actions and actions with parameters, the webui could just show a modal for the ones with params, and we could re-use the dynamic UI schema for it.
At some point we should also create a spec to rewrite dynamic UI schema generation 😔

Probably the way to go

I don't really understand what is being discussed. I went and looked at RemoveRecordsWithoutPhysicalFiles and it is just an async function that accepts parameters so ActionExecutionJob can just call that.

Gap 23 is more about the shape of the new dynamic action class and how parameters are passed to it, since v1 of this spec there is a requirement that Execute stays parameter-less.

If there is a problem with this design then it needs to be changed.

[harshithmohan]

@hidden4003 We currently do have actions with parameters so we cannot go parameter-less. It needs to be fixed.
There are also series level actions that take parameters in the current system. Not having paramaters would be a regression.

[hidden4003]

@hidden4003 We currently do have actions with parameters so we cannot go parameter-less. It needs to be fixed. There are also series level actions that take parameters in the current system. Not having paramaters would be a regression.

Not what I am talking about. I never said Action itself can't have parameters. Specifically the Execute method can't have parameters other than cancellation token, which means you can't pass parameters into the Execute and need to do it some other way, and that is what Gap 23 is describing, the other way of passing parameters to code inside Execute.

[hidden4003]

@da3dsoul @harshithmohan @revam I have restored full gap tracker and generated a reference implementation which should hopefully make it easier to see how the actual code might looks like (at least for me) and hopefully surfaces what we are missing to finalize the spec,

[harshithmohan]

For parameters, we can have booleans, string lists, or numbers etc but we shouldn't have nested parameters in objects

[harshithmohan]

Gap 6 Proposal: Endpoint Shape

Listing: Single endpoint with scope query parameter. Actions are identical across all entities of the same type — having entity-ID-scoped listing routes would be pure boilerplate duplication.

GET /api/v3/Action?scope=Series

• scope is optional. Omission returns all registered actions (useful for debugging).
• Valid values: Global, Group, Series, Episode.

Invocation: Per-entity routes because the entity ID is real execution context that gets resolved before the action is enqueued.

POST /api/v3/Action/{actionId}                           // Global
POST /api/v3/Group/{groupId}/Action/{actionId}            // Group
POST /api/v3/Series/{seriesId}/Action/{actionId}          // Series
POST /api/v3/Episode/{episodeId}/Action/{actionId}        // Episode

• No /Execute suffix — POST to an Action/{id} path implies invocation.
• Entity existence validated before enqueue. Returns 404 if the entity isn't found.
• Returns 200 (accepted) or 400 (rejected by Validate pre-check with reason).

Rationale against split listing routes: The controller implementation already has a single GetActions(scope) call. Splitting it into GET /api/v3/Group/Action, GET /api/v3/Series/Action, etc. just duplicates routing and controller code with zero behavioral difference.

Rationale for split invoke routes: The entity ID is a meaningful part of the resource path — POST /Series/42/Action/{actionId} reads as "invoke this action on series 42." Collapsing it to a query parameter loses that clarity and is less idiomatic REST.

Summary: 1 listing route + 4 invoke routes = 5 total.

[harshithmohan]

Gap 16 -> Out of scope for this discussion. If the server side changes are done, the webui can still defer the modal for later. For now it send nothing. BUT on the assumption that if a certain parameter is not sent for an action with parameters, it would have a default already set which can be used.

Gap 25/31 -> There is no consumer for the return data from Execute, so it can just log. So option 3

[hidden4003]

Updated the spec, everything seems resolved now

[revam]

I suggest we add a new scope Video linked to an IVideo (abstraction) / VideoLocal (internal), as it will be useful both for the core to expose it's per-video actions, such as "Add to MyList" / "Remove from MyList", "AVDump File", etc., and for plugins to add their per-video actions which don't belong to the Episode, Series, Group, or Global scopes.

[harshithmohan]

Gap 27 follow-up: the WebUI has no content for the confirmation prompt

RequiresConfirmation tells the WebUI when to prompt, but not what to say. Two constraints make a client-side fix impossible:

• Action IDs are UUIDv5 and deliberately unstable across renames (Gap 5), so the WebUI can't maintain a per-action message map.
• Plugins register actions the WebUI has never seen; any hardcoded copy would miss them entirely.

Description is also the wrong voice — it's declarative ("This can overwrite AniDB data irreversibly."), while a confirmation needs an interrogative line ("Do you want to…?"). Deriving a question from a description string is fragile.

Proposal: add an optional per-action confirmation message with a generic client-side fallback.

public interface IExecutableAction
{
    // ... existing members ...

    /// <summary>
    /// Interrogative prompt shown by the WebUI before invoking when
    /// RequiresConfirmation is true (e.g. "Do you want to overwrite all
    /// AniDB MyList state?"). Null → WebUI falls back to a generic prompt.
    /// </summary>
    string? ConfirmationMessage => null;
}

And on ActionInfo / ExecutableActionInfo:

public string? ConfirmationMessage { get; set; } // mapped through like Name/Description

WebUI behavior: when RequiresConfirmation is true, show ConfirmationMessage if present; otherwise show a generic "Are you sure you want to run \"{Name}\"?", with Description displayed as body context in both cases. Invoke proceeds only on confirm.

Backward compatibility: fully additive. Core actions migrate at their own pace, plugins opt in, and every action without one still gets a sane generic prompt. This closes the loop Gap 27 opened — the flag currently obligates the WebUI to prompt while handing it nothing to prompt with.