feat(plugins): MossTank — a self-buffing plugin, and the automation surface it needed

First consumer of acdream's plugin automation surface, and the first slice of
the VTank-class plugin milestone
(docs/research/2026-07-29-vtank-plugin-automation-requirements.md).

MossTank shows a panel with a Buff button; clicking it casts every self-buff
the character is missing, skips what is already in force at an equal or higher
tier, and refreshes what is nearly expired.

The host/plugin line is the load-bearing decision here. The host publishes
spell DATA -- family, tier, difficulty, mana, duration -- plus a cast
primitive with a preflight gate. The plugin owns the POLICY. That is the
architectural conclusion the requirements research reached: VTank's engine
lived in plugin-land, built on Decal's primitives, and baking "best buff for
skill X" into the host would start pulling the engine inward one convenience
at a time.

Why the plan is driven off the spellbook rather than off trained skills, which
is the obvious reading of "buff every trained and specialised skill": the
client cannot honestly make that mapping. The link between a spell and the
stat it modifies arrives from the SERVER in the enchantment message and is
absent from the client's own spell table. What the client does know is which
spells the character has learned -- and a character only learns buffs for the
skills they use, so the spellbook reaches the same set without inventing a
mapping the client has no grounds for.

Surface added, all BCL-only so Plugin.Abstractions keeps its zero project
references:

* ICharacterInfo, ISpellCatalog, IMagicCommands, grouped behind one
  IAutomationSurface so IPluginHost grows by one member rather than three.
* IEvents.Tick. Automation is sequences, not single calls -- a buff pass casts
  several spells and must wait between them. Without a host tick a plugin
  would need its own timer thread re-entering the host off its update thread.
* NoOpAutomationSurface for hosts with no live session, so a plugin keeps one
  code path and checks IsAvailable.

Markup gained <button> and <label>; it previously supported only <meter>, with
a comment promising the rest. Buttons bind onclick to an Action property and
FAIL THE PANEL LOAD if it does not resolve -- a silently dead button is worse
than a panel that refuses to load, because the user clicks and there is
nothing to diagnose. Labels bind through a Func so a status line tracks its
binding instead of freezing at build time.

Enchantment reads use EnchantmentsInEffectSnapshot rather than the raw active
set: retail leaves a weaker same-family enchantment in the registry while a
stronger one is in force, and a plugin asking "am I buffed?" means in force.

BuffPlan is a pure function of (known buffs, active enchantments) precisely so
it can be tested without a session; 9 tests cover tier supersede, the
family-0 no-stack bucket that must not be de-duplicated, expiry refresh, and
plan stability across the rebuilds the tick loop performs.

Solution builds clean; 14,421 tests pass on the standard hermetic lane filter,
0 failures.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

src/AcDream.Plugins.MossTank/AcDream.Plugins.MossTank.csproj

@@ -0,0 +1,26 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <LangVersion>latest</LangVersion>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <!-- Plugin DLLs are copied to plugins/<id>/ at build of AcDream.App.
+         They must NOT bring AcDream.Plugin.Abstractions.dll with them;
+         the host already owns it. -->
+  </PropertyGroup>
+  <ItemGroup>
+    <InternalsVisibleTo Include="AcDream.Plugins.MossTank.Tests" />
+  </ItemGroup>
+  <ItemGroup>
+    <ProjectReference Include="..\AcDream.Plugin.Abstractions\AcDream.Plugin.Abstractions.csproj">
+      <Private>false</Private>
+      <ExcludeAssets>runtime</ExcludeAssets>
+    </ProjectReference>
+  </ItemGroup>
+  <ItemGroup>
+    <None Update="mosstank.xml">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+</Project>

src/AcDream.Plugins.MossTank/BuffPlan.cs

@@ -0,0 +1,109 @@
+using AcDream.Plugin.Abstractions;
+
+namespace AcDream.Plugins.MossTank;
+
+/// <summary>
+/// Decides which self-buffs are missing and in what order to cast them.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Pure function of (known self-buffs, active enchantments). No host calls, no
+/// state, no clock — so the buff policy can be reasoned about and tested
+/// without a live session, which is the whole reason it lives here rather than
+/// in the host.
+/// </para>
+/// <para>
+/// <b>Why the spellbook is the source of truth.</b> The obvious reading of
+/// "buff every trained and specialised skill" is to enumerate skills and map
+/// each to its buff line. The client cannot do that honestly: the link between
+/// a spell and the stat it modifies arrives from the <em>server</em>, in the
+/// enchantment message, and is absent from the client's own spell table. What
+/// the client does know is which spells the character has learned — and a
+/// character only learns the buffs for the skills they actually use. Driving
+/// from the spellbook reaches the same set without inventing a mapping the
+/// client has no grounds for.
+/// </para>
+/// </remarks>
+internal static class BuffPlan
+{
+    /// <summary>
+    /// The strongest known buff per family that is not already in force at an
+    /// equal or higher tier, ordered so the plan is stable between passes.
+    /// </summary>
+    public static List<PluginSpellInfo> Build(
+        IReadOnlyList<PluginSpellInfo> knownSelfBuffs,
+        IReadOnlyList<PluginActiveEnchantment> active,
+        double refreshWhenUnderSeconds)
+    {
+        // Best known candidate per family. Family 0 is retail's "does not
+        // stack" bucket: those spells share no family identity, so collapsing
+        // them would drop all but one unrelated buff.
+        var bestByFamily = new Dictionary<uint, PluginSpellInfo>();
+        var unstackable = new List<PluginSpellInfo>();
+
+        foreach (PluginSpellInfo spell in knownSelfBuffs)
+        {
+            if (spell.Family == 0)
+            {
+                unstackable.Add(spell);
+                continue;
+            }
+            if (!bestByFamily.TryGetValue(spell.Family, out PluginSpellInfo held)
+                || spell.Tier > held.Tier)
+            {
+                bestByFamily[spell.Family] = spell;
+            }
+        }
+
+        // Strongest in-force tier per family, and how long it has left.
+        var activeByFamily = new Dictionary<uint, (int Tier, double Seconds)>();
+        var activeSpellSeconds = new Dictionary<uint, double>();
+        foreach (PluginActiveEnchantment enchantment in active)
+        {
+            activeSpellSeconds[enchantment.SpellId] = enchantment.SecondsRemaining;
+            if (enchantment.Family == 0)
+                continue;
+            if (!activeByFamily.TryGetValue(enchantment.Family, out var held)
+                || enchantment.Tier > held.Tier)
+            {
+                activeByFamily[enchantment.Family] =
+                    (enchantment.Tier, enchantment.SecondsRemaining);
+            }
+        }
+
+        var plan = new List<PluginSpellInfo>();
+
+        foreach (PluginSpellInfo candidate in bestByFamily.Values)
+        {
+            if (!activeByFamily.TryGetValue(candidate.Family, out var inForce))
+            {
+                plan.Add(candidate);
+                continue;
+            }
+            // A weaker enchantment in force is still worth replacing: recasting
+            // at a higher tier supersedes it.
+            if (candidate.Tier > inForce.Tier
+                || inForce.Seconds < refreshWhenUnderSeconds)
+            {
+                plan.Add(candidate);
+            }
+        }
+
+        foreach (PluginSpellInfo candidate in unstackable)
+        {
+            if (!activeSpellSeconds.TryGetValue(candidate.SpellId, out double seconds)
+                || seconds < refreshWhenUnderSeconds)
+            {
+                plan.Add(candidate);
+            }
+        }
+
+        // Cheapest first: if mana runs out mid-pass, more buffs landed than if
+        // the expensive ones had gone first.
+        plan.Sort(static (a, b) =>
+            a.ManaCost != b.ManaCost
+                ? a.ManaCost.CompareTo(b.ManaCost)
+                : a.SpellId.CompareTo(b.SpellId));
+        return plan;
+    }
+}

src/AcDream.Plugins.MossTank/MossTankPanel.cs

@@ -0,0 +1,184 @@
+using AcDream.Plugin.Abstractions;
+
+namespace AcDream.Plugins.MossTank;
+
+/// <summary>
+/// The panel's binding object and the buff loop's state machine.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The markup binds <c>{Buff}</c> to <see cref="Buff"/> and its labels to the
+/// status properties. Everything here runs on the host's update thread — the
+/// button click and the tick both arrive there — so no locking is needed, and
+/// none is used, deliberately: adding a lock would imply a second thread that
+/// does not exist.
+/// </para>
+/// <para>
+/// <b>Pacing.</b> The loop casts one spell, then waits. There is no
+/// cast-completed event in the plugin API yet, so completion is inferred the
+/// honest way: re-evaluate the plan each pass and let landed buffs drop out of
+/// it. A fizzle simply leaves its buff missing and it gets retried on the next
+/// pass. That is self-correcting without pretending to know an outcome the
+/// host has not reported.
+/// </para>
+/// </remarks>
+internal sealed class MossTankPanel
+{
+    /// <summary>Roughly a retail cast plus windup, so casts do not stack up.</summary>
+    private const double CastIntervalSeconds = 3.0;
+
+    /// <summary>Refresh a buff already in force but nearly expired.</summary>
+    private const double RefreshWhenUnderSeconds = 60.0;
+
+    /// <summary>Give up on a pass that stops making progress.</summary>
+    private const double StallTimeoutSeconds = 20.0;
+
+    private readonly IPluginHost _host;
+
+    private List<PluginSpellInfo> _plan = new();
+    private int _planIndex;
+    private bool _running;
+    private double _sinceLastCast;
+    private double _sinceProgress;
+    private int _castThisPass;
+    private string _status = "Idle.";
+
+    public MossTankPanel(IPluginHost host) => _host = host;
+
+    /// <summary>Bound to the panel's Buff button.</summary>
+    public Action Buff => StartOrStop;
+
+    public string Title => "MossTank";
+    public string Status => _status;
+
+    public string ButtonText => _running ? "Stop" : "Buff";
+
+    public string Detail
+    {
+        get
+        {
+            IAutomationSurface automation = _host.Automation;
+            if (!automation.IsAvailable)
+                return "Not in world.";
+            int known = automation.Spells.KnownSelfBuffs.Count;
+            int active = automation.Character.ActiveEnchantments.Count;
+            return $"{known} self-buffs known / {active} active"
+                + $"  ·  mana {automation.Character.CurrentMana}"
+                + $"/{automation.Character.MaxMana}";
+        }
+    }
+
+    private void StartOrStop()
+    {
+        if (_running)
+        {
+            Stop("Stopped.");
+            return;
+        }
+
+        IAutomationSurface automation = _host.Automation;
+        if (!automation.IsAvailable)
+        {
+            _status = "Not in world.";
+            return;
+        }
+
+        _plan = BuffPlan.Build(
+            automation.Spells.KnownSelfBuffs,
+            automation.Character.ActiveEnchantments,
+            RefreshWhenUnderSeconds);
+        _planIndex = 0;
+        _castThisPass = 0;
+        _sinceLastCast = CastIntervalSeconds;   // cast the first one immediately
+        _sinceProgress = 0;
+
+        if (_plan.Count == 0)
+        {
+            _status = "Already fully buffed.";
+            return;
+        }
+
+        _running = true;
+        _status = $"Buffing 0/{_plan.Count}…";
+        _host.Log.Info($"MossTank: buff pass started, {_plan.Count} spell(s) to cast");
+    }
+
+    private void Stop(string status)
+    {
+        _running = false;
+        _plan = new List<PluginSpellInfo>();
+        _planIndex = 0;
+        _status = status;
+    }
+
+    /// <summary>Driven by <see cref="IEvents.Tick"/> on the host update thread.</summary>
+    public void OnTick(double elapsedSeconds)
+    {
+        if (!_running)
+            return;
+
+        IAutomationSurface automation = _host.Automation;
+        if (!automation.IsAvailable)
+        {
+            Stop("Lost the session.");
+            return;
+        }
+
+        _sinceLastCast += elapsedSeconds;
+        _sinceProgress += elapsedSeconds;
+
+        if (_sinceProgress > StallTimeoutSeconds)
+        {
+            Stop($"Stalled after {_castThisPass} cast(s).");
+            _host.Log.Warn("MossTank: buff pass stalled; stopping");
+            return;
+        }
+
+        if (_sinceLastCast < CastIntervalSeconds || automation.Magic.IsCasting)
+            return;
+
+        // Re-derive against current enchantments so anything that landed since
+        // the pass began drops out rather than being cast twice.
+        _plan = BuffPlan.Build(
+            automation.Spells.KnownSelfBuffs,
+            automation.Character.ActiveEnchantments,
+            RefreshWhenUnderSeconds);
+
+        if (_plan.Count == 0)
+        {
+            Stop($"Done — {_castThisPass} cast(s).");
+            _host.Log.Info($"MossTank: buff pass complete ({_castThisPass} cast)");
+            return;
+        }
+
+        if (_planIndex >= _plan.Count)
+            _planIndex = 0;
+
+        PluginSpellInfo next = _plan[_planIndex];
+        PluginCastGate gate = automation.Magic.EvaluateGate(next.SpellId);
+        if (gate != PluginCastGate.Ready)
+        {
+            // Skip it rather than blocking the pass; the next tick tries the
+            // one after. A permanently ungateable spell falls out when the
+            // stall timeout fires.
+            _planIndex++;
+            _status = $"Skipped {next.Name} ({gate}).";
+            return;
+        }
+
+        if (automation.Magic.Cast(next.SpellId))
+        {
+            _castThisPass++;
+            _sinceLastCast = 0;
+            _sinceProgress = 0;
+            _planIndex = 0;
+            _status = $"Casting {next.Name} ({_castThisPass} cast)…";
+            _host.Log.Info($"MossTank: casting {next.Name} (0x{next.SpellId:X4})");
+        }
+        else
+        {
+            _planIndex++;
+            _status = $"Refused {next.Name}.";
+        }
+    }
+}

src/AcDream.Plugins.MossTank/MossTankPlugin.cs

@@ -0,0 +1,59 @@
+using AcDream.Plugin.Abstractions;
+
+namespace AcDream.Plugins.MossTank;
+
+/// <summary>
+/// MossTank — a self-buffing plugin, and the first consumer of acdream's
+/// plugin automation surface.
+/// </summary>
+/// <remarks>
+/// Named for the mosswart, and for the Virindi Tank lineage this milestone is
+/// modelled on. The buff policy lives here rather than in the host on purpose:
+/// the host publishes spell data and a cast primitive, the plugin decides what
+/// to cast. See <c>docs/research/2026-07-29-vtank-plugin-automation-requirements.md</c>.
+/// </remarks>
+public sealed class MossTankPlugin : IAcDreamPlugin
+{
+    private IPluginHost? _host;
+    private MossTankPanel? _panel;
+    private Action<double>? _tick;
+
+    public void Initialize(IPluginHost host)
+    {
+        _host = host;
+        _panel = new MossTankPanel(host);
+        host.Log.Info("MossTank initialized");
+    }
+
+    public void Enable()
+    {
+        if (_host is null || _panel is null)
+            return;
+
+        // Markup ships beside the plugin assembly, so it is found relative to
+        // this DLL rather than the host's working directory -- plugins are
+        // loaded from their own directory and the two are not the same.
+        string markup = Path.Combine(
+            Path.GetDirectoryName(typeof(MossTankPlugin).Assembly.Location) ?? ".",
+            "mosstank.xml");
+
+        _host.Ui.AddMarkupPanel(markup, _panel);
+
+        _tick = _panel.OnTick;
+        _host.Events.Tick += _tick;
+
+        _host.Log.Info(
+            _host.Automation.IsAvailable
+                ? "MossTank enabled"
+                : "MossTank enabled (no live session yet; the Buff button will "
+                  + "report 'Not in world' until one is up)");
+    }
+
+    public void Disable()
+    {
+        if (_host is not null && _tick is not null)
+            _host.Events.Tick -= _tick;
+        _tick = null;
+        _host?.Log.Info("MossTank disabled");
+    }
+}

src/AcDream.Plugins.MossTank/mosstank.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- MossTank's panel. Bindings resolve by property name against MossTankPanel:
+     {Buff} is an Action bound to the button, the rest are read every frame. -->
+<panel x="40" y="120" w="300" h="118" title="MossTank">
+  <label  x="12" y="28" text="{Detail}" color="#FFB9C7A0" />
+  <label  x="12" y="48" text="{Status}" color="#FFE8E4C8" />
+  <button x="12" y="72" w="104" h="28" text="Buff" onclick="{Buff}" />
+</panel>

src/AcDream.Plugins.MossTank/packages.neutral.lock.json

@@ -0,0 +1,10 @@
+{
+  "version": 2,
+  "dependencies": {
+    "net10.0": {
+      "acdream.plugin.abstractions": {
+        "type": "Project"
+      }
+    }
+  }
+}