feat(akka): capture Akka.NET DeadLetters into the Bowire stream

BowireAkkaExtension now subscribes a tiny internal listener actor to the
actor system's EventStream for DeadLetter notifications and republishes
them through the same broadcast channel as mailbox taps. A new optional
IsDeadLetter flag on TappedMessage (default false, backwards-compatible)
lets the Bowire UI distinguish undeliverable messages without extra
plumbing. The subscription is torn down via RegisterOnTermination when
the system shuts down.

Adds BowireDeadLetterTests covering the EventStream path: stop an actor,
Tell to its now-dead ref, assert the subscriber sees a TappedMessage with
IsDeadLetter=true and the recipient set to the system's dead-letters
path. Bumps version to 0.10.0 and moves DeadLetters out of the roadmap
into "What it does".

Author: thomas-stegemann

Directory.Build.props

@@ -38,9 +38,9 @@
   </PropertyGroup>
 
   <PropertyGroup Condition="'$(IsPackable)' != 'false'">
-    <Version>0.9.4</Version>
-    <AssemblyVersion>0.9.4</AssemblyVersion>
-    <FileVersion>0.9.4</FileVersion>
+    <Version>0.10.0</Version>
+    <AssemblyVersion>0.10.0</AssemblyVersion>
+    <FileVersion>0.10.0</FileVersion>
   </PropertyGroup>
 
   <PropertyGroup Condition="$(MSBuildProjectName.StartsWith('Kuestenlogik.Bowire.Protocol.'))">

README.md

@@ -9,7 +9,8 @@ Bowire protocol plugin for **[Akka.NET](https://getakka.net/)** actor systems. S
 
 - **Mailbox tap** — a custom Akka.NET `MailboxType` (`BowireTapMailbox`) wraps the standard unbounded queue and forwards every enqueue to a per-actor-system extension. Opt-in globally (default mailbox swap) or per-actor (`Props.WithMailbox(...)`).
 - **`IExtension` integration** — `BowireAkkaExtension` owns the broadcast channel and the active subscriber list. Steady-state cost when nobody's watching: one volatile read per message.
-- **Bowire streaming pane** — `BowireAkkaProtocol` exposes one server-streaming method, `Tap/MonitorMessages`, that yields `TappedMessage` envelopes (recipient path, sender path, CLR type, payload, timestamp) as JSON.
+- **DeadLetters capture** — the extension subscribes to the actor system's `EventStream` and republishes every `Akka.Event.DeadLetter` through the same channel with `TappedMessage.IsDeadLetter = true`, so undeliverable messages surface in the Bowire stream without any per-actor opt-in.
+- **Bowire streaming pane** — `BowireAkkaProtocol` exposes one server-streaming method, `Tap/MonitorMessages`, that yields `TappedMessage` envelopes (recipient path, sender path, CLR type, payload, timestamp, dead-letter flag) as JSON.
 
 ## Install
 
@@ -66,9 +67,10 @@ dotnet run --project samples/Kuestenlogik.Bowire.Protocol.Akka.Sample
 
 ## Roadmap
 
-- **0.1.0** (current) — embedded mode, `EventStream`-style mailbox tap, JSON envelope of recipient/sender/type/payload/timestamp.
-- **0.2.0** — external `Akka.Cluster.Tools.ClusterClient` transport so the standalone `bowire` CLI can attach to a running cluster, mailbox-snapshot inspection (size, head messages), `DeadLetters` capture, per-actor throughput stats.
-- **0.3.0** — typed payload via Akka serializer roundtrip, opt-in filter API from the Bowire UI (per actor path, per message type), Tell-from-Bowire (interactive duplex).
+- **0.1.0** — embedded mode, `EventStream`-style mailbox tap, JSON envelope of recipient/sender/type/payload/timestamp.
+- **0.2.0** (current) — `DeadLetters` capture via `EventStream` subscription with `IsDeadLetter` flag on the envelope.
+- **0.3.0** — external `Akka.Cluster.Tools.ClusterClient` transport so the standalone `bowire` CLI can attach to a running cluster, mailbox-snapshot inspection (size, head messages), per-actor throughput stats.
+- **0.4.0** — typed payload via Akka serializer roundtrip, opt-in filter API from the Bowire UI (per actor path, per message type), Tell-from-Bowire (interactive duplex).
 
 ## License
 

src/Kuestenlogik.Bowire.Protocol.Akka/BowireAkkaExtension.cs

@@ -3,6 +3,7 @@
 
 using System.Threading.Channels;
 using Akka.Actor;
+using Akka.Event;
 
 namespace Kuestenlogik.Bowire.Protocol.Akka;
 
@@ -17,6 +18,13 @@ namespace Kuestenlogik.Bowire.Protocol.Akka;
 /// <see cref="ChannelReader{T}"/> that receives every tap from now on.
 /// Multiple subscribers each get their own reader — no fan-out coupling.
 /// </para>
+/// <para>
+/// The extension also subscribes to the actor system's
+/// <see cref="EventStream"/> for <see cref="DeadLetter"/> events and
+/// republishes them through the same channel with
+/// <see cref="TappedMessage.IsDeadLetter"/> set, so undeliverable messages
+/// surface in the Bowire stream without any per-actor opt-in.
+/// </para>
 /// </summary>
 /// <remarks>
 /// The tap mailbox queries this extension on every enqueue; if no
@@ -28,13 +36,40 @@ public sealed class BowireAkkaExtension : IExtension
 {
     private readonly object _lock = new();
     private readonly List<Channel<TappedMessage>> _subscribers = [];
+    private readonly IActorRef _deadLetterListener;
+    private readonly string _deadLetterPath;
 
     /// <summary>The actor system this extension instance belongs to.</summary>
     public ExtendedActorSystem System { get; }
 
     internal BowireAkkaExtension(ExtendedActorSystem system)
     {
         System = system;
+        _deadLetterPath = system.DeadLetters.Path.ToString();
+
+        // Subscribe a lightweight internal actor to the EventStream for
+        // DeadLetter notifications. We use an actor (rather than a raw
+        // delegate) because Akka.NET's EventStream API is actor-based —
+        // ActorOf gives us automatic lifecycle handling.
+        _deadLetterListener = system.SystemActorOf(
+            Props.Create(() => new DeadLetterListener(this)),
+            "bowire-deadletter-listener");
+        system.EventStream.Subscribe(_deadLetterListener, typeof(DeadLetter));
+
+        // Tear down the subscription when the system shuts down so we
+        // don't leak the EventStream registration. IExtension has no
+        // dispose hook, so RegisterOnTermination is the standard knob.
+        system.RegisterOnTermination(() =>
+        {
+            try
+            {
+                System.EventStream.Unsubscribe(_deadLetterListener, typeof(DeadLetter));
+            }
+            catch
+            {
+                // Best-effort cleanup during shutdown; swallow.
+            }
+        });
     }
 
     /// <summary>
@@ -105,6 +140,60 @@ internal void Publish(TappedMessage msg)
             ch.Writer.TryWrite(msg);
         }
     }
+
+    /// <summary>
+    /// Convert a <see cref="DeadLetter"/> from the actor system's
+    /// <see cref="EventStream"/> into a <see cref="TappedMessage"/> with
+    /// <see cref="TappedMessage.IsDeadLetter"/> set, then fan-out via the
+    /// regular <see cref="Publish"/> path. Wrapped in try/catch because a
+    /// broken <see cref="object.ToString"/> on a payload must never break
+    /// the listener actor.
+    /// </summary>
+    internal void PublishDeadLetter(DeadLetter deadLetter)
+    {
+        try
+        {
+            var msg = deadLetter.Message;
+            Publish(new TappedMessage(
+                Recipient: _deadLetterPath,
+                Sender: deadLetter.Sender?.Path?.ToString() ?? string.Empty,
+                MessageType: msg?.GetType().FullName ?? "<null>",
+                Payload: msg?.ToString() ?? string.Empty,
+                Timestamp: DateTime.UtcNow,
+                IsDeadLetter: true));
+        }
+        catch
+        {
+            // Diagnostics must never crash the actor system. Swallow.
+        }
+    }
+
+#pragma warning disable CA1812 // Instantiated by Akka via Props.Create
+    /// <summary>
+    /// Tiny internal actor that bridges the <see cref="EventStream"/>'s
+    /// actor-based subscription API back into the
+    /// <see cref="BowireAkkaExtension"/>'s plain method call. Holding a
+    /// reference to the extension is fine: the extension's lifetime is the
+    /// actor system's.
+    /// </summary>
+    private sealed class DeadLetterListener : UntypedActor
+    {
+        private readonly BowireAkkaExtension _extension;
+
+        public DeadLetterListener(BowireAkkaExtension extension)
+        {
+            _extension = extension;
+        }
+
+        protected override void OnReceive(object message)
+        {
+            if (message is DeadLetter dl)
+            {
+                _extension.PublishDeadLetter(dl);
+            }
+        }
+    }
+#pragma warning restore CA1812
 }
 
 /// <summary>

src/Kuestenlogik.Bowire.Protocol.Akka/TappedMessage.cs

@@ -7,8 +7,9 @@ namespace Kuestenlogik.Bowire.Protocol.Akka;
 
 /// <summary>
 /// One observation of a message landing in (or sent to) an actor's mailbox.
-/// Captured by <see cref="BowireTapMessageQueue"/> on enqueue and
-/// forwarded to <see cref="BowireAkkaExtension"/>'s broadcast channel.
+/// Captured by <see cref="BowireTapMessageQueue"/> on enqueue — or by the
+/// <see cref="BowireAkkaExtension"/>'s <c>DeadLetter</c> subscription on
+/// undelivered envelopes — and forwarded to the broadcast channel.
 /// </summary>
 /// <param name="Recipient">Absolute actor path of the receiver.</param>
 /// <param name="Sender">Absolute path of the sender, or <c>deadLetters</c>.</param>
@@ -19,9 +20,17 @@ namespace Kuestenlogik.Bowire.Protocol.Akka;
 /// or System.Text.Json for richer inspection.
 /// </param>
 /// <param name="Timestamp">UTC timestamp of the enqueue.</param>
+/// <param name="IsDeadLetter">
+/// True when this observation came from the actor system's
+/// <c>Akka.Event.EventStream</c> as an <c>Akka.Event.DeadLetter</c> rather
+/// than from a tapped mailbox enqueue. Lets the Bowire UI style
+/// undeliverable messages distinctly. Defaults to <c>false</c> for
+/// backwards compatibility.
+/// </param>
 public sealed record TappedMessage(
     string Recipient,
     string Sender,
     string MessageType,
     string Payload,
-    DateTime Timestamp);
+    DateTime Timestamp,
+    bool IsDeadLetter = false);

tests/Kuestenlogik.Bowire.Protocol.Akka.Tests/BowireDeadLetterTests.cs

@@ -0,0 +1,76 @@
+// Copyright 2026 Küstenlogik
+// SPDX-License-Identifier: Apache-2.0
+
+using Akka.Actor;
+
+namespace Kuestenlogik.Bowire.Protocol.Akka.Tests;
+
+public sealed class BowireDeadLetterTests
+{
+    [Fact]
+    public async Task Subscriber_ReceivesDeadLetter_FromEventStream()
+    {
+        using var system = ActorSystem.Create("test-deadletter");
+        var ext = BowireAkkaExtensionProvider.Instance.Apply((ExtendedActorSystem)system);
+
+        var reader = ext.Subscribe(out var token);
+        try
+        {
+            // Tell to a terminated actor → Akka publishes a DeadLetter on
+            // the EventStream. We stop the actor and then send to it; the
+            // mailbox is gone so the message can't be delivered.
+            var doomed = system.ActorOf(NoopActor.Build(), "doomed");
+            await doomed.GracefulStop(TimeSpan.FromSeconds(2));
+            doomed.Tell("orphan-message");
+
+            // Read messages until we find one flagged as a dead letter
+            // (the gracefulStop poison-pill itself doesn't end up as a
+            // dead letter, but defensive filtering keeps the assertion
+            // crisp).
+            using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
+            TappedMessage? deadLetter = null;
+            while (!cts.IsCancellationRequested)
+            {
+                var got = await reader.ReadAsync(cts.Token);
+                if (got.IsDeadLetter && got.Payload == "orphan-message")
+                {
+                    deadLetter = got;
+                    break;
+                }
+            }
+
+            Assert.NotNull(deadLetter);
+            Assert.True(deadLetter!.IsDeadLetter);
+            Assert.Equal("System.String", deadLetter.MessageType);
+            Assert.Equal("orphan-message", deadLetter.Payload);
+            Assert.Equal(system.DeadLetters.Path.ToString(), deadLetter.Recipient);
+        }
+        finally
+        {
+            ext.Unsubscribe(token);
+        }
+    }
+
+    [Fact]
+    public void RegularTappedMessage_HasIsDeadLetterFalseByDefault()
+    {
+        // Backwards-compatibility check — the new optional parameter
+        // defaults to false so callers from before 0.2.0 keep working.
+        var msg = new TappedMessage(
+            Recipient: "akka://test/user/foo",
+            Sender: "akka://test/user/bar",
+            MessageType: "System.String",
+            Payload: "hi",
+            Timestamp: DateTime.UtcNow);
+
+        Assert.False(msg.IsDeadLetter);
+    }
+
+#pragma warning disable CA1812 // Akka instantiates these via reflection in Props.Create<T>()
+    private sealed class NoopActor : UntypedActor
+    {
+        public static Props Build() => global::Akka.Actor.Props.Create<NoopActor>();
+        protected override void OnReceive(object message) { /* no-op */ }
+    }
+#pragma warning restore CA1812
+}