@carlitose86/pi-telegram-reactive 0.1.0-next.0 → 0.1.0-next.1

package/CHANGELOG.md

@@ -4,7 +4,11 @@
 
 ## Unreleased
 
-No additional changes beyond the preview candidate below.
+No additional changes beyond the preview candidates below.
+
+## 0.1.0-next.1: Dropped-reply diagnostics
+
+- `Dropped final replies`: When the bridge deliberately does not deliver a final reply that had text, attachments or an error notice, because the session was replaced, the transport changed or the active turn moved, it now records one redacted `delivery` event with a `final-reply-*` phase instead of leaving no trace. Runs with nothing to publish stay silent. A regression covers final replies after mid-run steers.
 
 ## 0.1.0-next.0: Pi Telegram Reactive preview candidate
 

package/README.md

@@ -17,7 +17,7 @@ Pi Telegram Reactive is the distinct `@carlitose86/pi-telegram-reactive` preview
 From npm:
 
 ```bash
-pi install npm:@carlitose86/pi-telegram-reactive@0.1.0-next.0
+pi install npm:@carlitose86/pi-telegram-reactive@0.1.0-next.1
 ```
 
 From git:

package/dist/lib/queue.js

@@ -875,10 +875,25 @@ export function buildTelegramAgentEndPlan(options) {
         shouldSendAttachmentNotice: false,
     };
 }
+/** Records a deliberately undelivered final reply without its content. */
+function recordTelegramDroppedFinalReply(recordRuntimeEvent, phase, turn, content) {
+    recordRuntimeEvent?.("delivery", new Error("Telegram final reply was not delivered."), {
+        phase,
+        hasTurn: !!turn,
+        hasThread: turn?.target?.threadId !== undefined,
+        textLength: content.text?.length ?? 0,
+        attachmentCount: content.attachmentCount ?? 0,
+    });
+}
 export function createTelegramAgentEndHook(deps) {
     return async (event, ctx, assistantOverride) => {
-        if (deps.isSessionActive?.(ctx) === false)
+        if (deps.isSessionActive?.(ctx) === false) {
+            const activeTurn = deps.getActiveTurn();
+            if (activeTurn) {
+                recordTelegramDroppedFinalReply(deps.recordRuntimeEvent, "final-reply-session-inactive", activeTurn, { attachmentCount: activeTurn.queuedAttachments.length });
+            }
             return;
+        }
         const turn = deps.getActiveTurn();
         const extractedAssistant = assistantOverride ?? (turn ? deps.extractAssistant(event.messages) : {});
         const assistant = deps.isAssistantAlreadyPublished?.(extractedAssistant)
@@ -889,8 +904,15 @@ export function createTelegramAgentEndHook(deps) {
         const scheduleDelivery = reservation?.schedule ?? deps.scheduleActiveTurnDelivery;
         try {
             await deps.loadConfig?.();
-            if (deps.isSessionActive?.(ctx) === false || deps.getActiveTurn() !== turn)
+            const sessionInactive = deps.isSessionActive?.(ctx) === false;
+            if (sessionInactive || deps.getActiveTurn() !== turn) {
+                if (hasPublication) {
+                    recordTelegramDroppedFinalReply(deps.recordRuntimeEvent, sessionInactive
+                        ? "final-reply-session-inactive"
+                        : "final-reply-turn-replaced", turn, { text: assistant.text, attachmentCount: turn?.queuedAttachments.length });
+                }
                 return;
+            }
             await handleTelegramAgentEndRuntime({
                 turn,
                 assistant,
@@ -964,8 +986,26 @@ export async function handleTelegramAgentEndRuntime(deps) {
     const finalText = outboundReply ? outboundReply.markdown : rawFinalText;
     const hasOutboundArtifacts = !!outboundReply?.voiceText || !!outboundReply?.voiceReplies?.length;
     const replyMarkup = outboundReply?.replyMarkup;
-    const isDeliveryActive = () => deps.isSessionActive?.() !== false &&
-        (!turn || deps.isTurnTransportActive?.(turn) !== false);
+    const hasPublishableContent = !!finalText ||
+        hasOutboundArtifacts ||
+        (turn?.queuedAttachments.length ?? 0) > 0 ||
+        assistant.stopReason === "error";
+    let dropRecorded = false;
+    // The first failed fence that would lose content leaves one diagnostic event;
+    // without it a dropped final reply is indistinguishable from a sent one.
+    const isDeliveryActive = () => {
+        const sessionActive = deps.isSessionActive?.() !== false;
+        const transportActive = !turn || deps.isTurnTransportActive?.(turn) !== false;
+        if (sessionActive && transportActive)
+            return true;
+        if (!dropRecorded && hasPublishableContent) {
+            dropRecorded = true;
+            recordTelegramDroppedFinalReply(deps.recordRuntimeEvent, sessionActive
+                ? "final-reply-transport-inactive"
+                : "final-reply-session-inactive", turn, { text: finalText, attachmentCount: turn?.queuedAttachments.length });
+        }
+        return false;
+    };
     const preview = turn && !turn.guestQueryId ? deps.preparePreviewDelivery?.(isDeliveryActive) : undefined;
     const setPreviewPendingText = preview?.setPreviewPendingText ?? deps.setPreviewPendingText;
     const finalizeMarkdownPreview = preview?.finalizeMarkdownPreview ?? deps.finalizeMarkdownPreview;

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carlitose86/pi-telegram-reactive",
-  "version": "0.1.0-next.0",
+  "version": "0.1.0-next.1",
   "private": false,
   "publishConfig": {
     "access": "public",

package/docs/specs/telegram-silent-reply-drop.md

@@ -0,0 +1,59 @@
+# Telegram final replies dropped without a trace
+
+## Artifact Graph
+- Artifact ID: `artifact:telegram-silent-reply-drop-spec`
+- Role: `spec`
+- Standalone: true
+### Children
+- [01 Record every dropped final reply](../tickets/telegram-silent-reply-drop/01-record-dropped-final-replies.md)
+- [02 Reproduce and fix the steered-run drop](../tickets/telegram-silent-reply-drop/02-reproduce-steered-run-drop.md)
+
+## Type and evidence
+Bug analysis. On 2026-10-07 a registered follower session (installed `@carlitose86/pi-telegram-reactive` `0.1.0-next.0`, built from `release/reactive-next-0`) produced two final assistant replies that never reached its Telegram Thread. Its session file shows the exact sequence (UTC):
+
+| Time | Event |
+| --- | --- |
+| 13:39:39 | Telegram prompt (from a prompt button) starts a run |
+| 13:39:46 | assistant `toolUse` |
+| 13:40:09 | Telegram prompt "Chi sarebbe il collega?" enters the same run |
+| 13:40:27 | assistant `stop`, answering both prompts |
+| 13:40:27 | Telegram prompt "Poi spiegami…" enters at that last `turn_end`, so the run continues |
+| 13:40:32–34 | assistant `toolUse` ×2 |
+| 13:40:59 | assistant `stop`; run settles |
+
+Neither reply was delivered, and `tmp/telegram/logs.jsonl` has no event after 13:33:28. Earlier replies of the same session, without mid-run prompts, arrived and left voice-fallback events. Inbound and leader polling stayed healthy.
+
+The final-reply path ends silently in several places:
+- `createTelegramAgentEndHook` returns when the session context is no longer current, or when the active turn changed while config loaded.
+- `handleTelegramAgentEndRuntime` returns when `isDeliveryActive()` is false (session inactive, or the turn's transport stamp is no longer current) and when there is no active turn at all.
+- An assistant text already admitted as an intermediate publication is reduced to its stop reason.
+
+None of these exits records a runtime event, so the logs cannot say which one fired. The transport stamp changes only with profile or bot-token changes, so a stale stamp is unlikely here; a missing active turn or a replaced turn during a run with mid-run steers (`createTelegramMidRunSteerRuntime`, added with the busy-run steering feature) is the leading hypothesis. It is not proven.
+
+## Goal
+A final reply produced for a Telegram turn reaches its exact Telegram target, and when the bridge deliberately does not deliver one it leaves a redacted diagnostic event naming the reason.
+
+## Non-goals
+- No change to voice fallback, prompt buttons or the leader/follower bus protocol unless the reproduction proves they cause the drop.
+- No replay of an uncertain send and no delivery to a different target, profile or session.
+- No mutation of journals, owners, locks or state files to recover lost replies.
+
+## Target behavior and invariants
+1. Every non-delivery exit of the final-reply path that discards assistant text, attachments or an error notice records one `delivery` runtime event with a stable `phase` per reason: `final-reply-session-inactive`, `final-reply-transport-inactive` or `final-reply-turn-replaced`. Event details hold only bounded, redacted facts: reason, turn and Thread presence, text length, attachment count; never the reply text.
+2. Exits that discard nothing (no text, no attachments, no error) stay silent. A run with no active Telegram turn is an ordinary local run whose output belongs to companion projection, and an answer already admitted as an intermediate publication is intentional deduplication; neither records an event, so routine runs do not flood the log. Slice 02 decides whether the observed drop went through the no-active-turn exit.
+3. A run started by a Telegram prompt that absorbs one or more mid-run Telegram steers, including a steer queued at the final `turn_end`, delivers its final reply to the original turn's target exactly once.
+4. Existing fences keep their meaning: a truly replaced session, profile or bot token still prevents delivery, now with an event.
+
+## Implementation slices
+- **01:** Add the diagnostic events of invariants 1–2 with unit tests for each reason. This alone makes any recurrence attributable.
+- **02:** Reproduce the observed sequence (prompt-button turn, mid-run steer after a tool turn, second steer at the final `turn_end`) in a lifecycle-level test with real bridge wiring and fake Pi events. If it reproduces, fix the root cause and keep the test. If it does not, record which paths were exercised, keep the test as a regression, and leave the ticket open for live evidence from slice 01's events.
+
+## Verification
+Unit tests for each event reason; a lifecycle/integration test for invariant 3; `npm run build`, `npm run typecheck`, `npm test`, `npm run build:check`. Live confirmation needs a paired Telegram Thread and is a manual step after installation; no live behavior is claimed from tests.
+
+## Gates
+- **Attempt:** one pull request in `carlitose/pi-telegram` targeting `release/reactive-next-0`.
+- **Budget and time per attempt:** at most 3 hours; no external spend. **Maximum attempts:** 2.
+- **Approvals:** the agent may merge the pull request once its required checks are green. Publishing `0.1.0-next.1` to npm is done by the user (`npm publish`, browser 2FA). Updating the pin in `pi-personal-config` and installing happen only after the running `dbh-crew` benchmark lot ends.
+- **Exact version:** none.
+- **Existing blocks found:** the `dbh-crew` lot is running (blocks only installation); open pull request #7 `release/reactive-next-0 → main` (does not block this branch). Searched: open pull requests, `package.json` version, repository workflows `validate.yml` and `release.yml`.

package/docs/tickets/telegram-silent-reply-drop/01-record-dropped-final-replies.md

@@ -0,0 +1,42 @@
+---
+ticket_schema: 1
+ticket_id: "01"
+execution_mode: AFK
+blocked_by: []
+---
+
+# Record every dropped final reply
+
+## Artifact Graph
+- Artifact ID: `artifact:telegram-silent-reply-drop-01`
+- Role: `ticket`
+- Parent: [telegram-silent-reply-drop.md](../../specs/telegram-silent-reply-drop.md)
+
+## Parent Spec
+[Telegram final replies dropped without a trace](../../specs/telegram-silent-reply-drop.md), target behavior 1, 2 and 4; slice 01.
+
+## What to Build
+Make each non-delivery exit of the final-reply path (`createTelegramAgentEndHook` and `handleTelegramAgentEndRuntime` in `lib/queue.ts`) that discards assistant text, queued attachments or an error notice record one redacted `delivery` runtime event with a stable `final-reply-*` phase naming the reason. Exits that discard nothing stay silent. Delivery behavior and fences do not change.
+
+## Acceptance Criteria
+- [ ] Session-inactive, transport-inactive, turn-replaced, no-active-turn and already-published exits each record exactly one event with their own phase when content would be lost.
+- [ ] Event details contain no reply text; only reason, text presence/length, attachment count and target presence.
+- [ ] A run with nothing to publish records no event.
+- [ ] Existing queue/lifecycle tests stay green; `dist/` is rebuilt.
+
+## Frontier
+Done: merged in #8 (`298f291`), CI green on Linux, macOS and Windows. Live events appear only after the package is published and installed.
+
+## Gates
+As the parent spec: one PR to `release/reactive-next-0`, 3 hours per attempt, at most 2 attempts; the agent may merge on green checks; npm publication by the user; installation only after the `dbh-crew` lot.
+
+## Step-by-Step Implementation Plan
+1. Add a failing unit test per reason in `tests/queue.test.ts`.
+2. Record the events at each exit through the existing `recordRuntimeEvent` port.
+3. `npm run build`, typecheck, focused then full tests.
+
+## Testing Plan
+Unit tests in `tests/queue.test.ts`; `npm run typecheck`; `npm test`; `npm run build:check`.
+
+## Out of Scope
+- Finding or fixing the root cause (ticket 02).

package/docs/tickets/telegram-silent-reply-drop/02-reproduce-steered-run-drop.md

@@ -0,0 +1,43 @@
+---
+ticket_schema: 1
+ticket_id: "02"
+execution_mode: AFK
+blocked_by:
+  - "01"
+---
+
+# Reproduce and fix the steered-run drop
+
+## Artifact Graph
+- Artifact ID: `artifact:telegram-silent-reply-drop-02`
+- Role: `ticket`
+- Parent: [telegram-silent-reply-drop.md](../../specs/telegram-silent-reply-drop.md)
+
+## Parent Spec
+[Telegram final replies dropped without a trace](../../specs/telegram-silent-reply-drop.md), target behavior 3 and 4; slice 02.
+
+## What to Build
+A lifecycle-level test with real bridge wiring and fake Pi events that replays the observed sequence: a Telegram prompt (from a prompt button) starts a run, one mid-run steer is injected after a tool turn, a second steer is injected at the final `turn_end` so the run continues, then the run settles. The final reply must reach the original turn's target exactly once. If the test reproduces the drop, fix the root cause. If it does not, keep it as a regression, document the exercised paths here, and leave the ticket open for live evidence from ticket 01's events.
+
+## Acceptance Criteria
+- [ ] The test covers both steers, including the one queued at the final `turn_end`.
+- [ ] With the fix, the final reply is sent once to the original target; no duplicate and no other target.
+- [ ] Replaced session, profile or token still blocks delivery and now records ticket 01's event.
+- [ ] `npm run typecheck`, `npm test` and `npm run build:check` pass.
+
+## Frontier
+Investigated, not reproduced. In the classic single-process runtime the final reply reaches the turn target once with 0, 1 and 2 mid-run steers, including one queued at the final `turn_end` (regression in `tests/integration.test.ts`). Not exercised: registered-follower delivery through the leader and a prompt-button origin, both present in the incident. Open until a live recurrence yields ticket 01's `final-reply-*` event, which names the failing fence.
+
+## Gates
+As the parent spec: one PR to `release/reactive-next-0`, 3 hours per attempt, at most 2 attempts; the agent may merge on green checks; npm publication by the user; installation only after the `dbh-crew` lot.
+
+## Step-by-Step Implementation Plan
+1. Locate the lifecycle test harness that drives `agent_start`/`turn_end`/`message_start`/`agent_end` with the mid-run steer runtime.
+2. Write the failing test for the observed sequence.
+3. Fix the smallest owning module; rebuild `dist/`.
+
+## Testing Plan
+Lifecycle/integration test in the mirrored suite; full `npm test`; live check in a paired Thread after installation (manual, not claimed).
+
+## Out of Scope
+- Voice fallback and leader/follower protocol changes unless the reproduction proves them causal.

package/lib/queue.ts

@@ -1759,6 +1759,28 @@ export function buildTelegramAgentEndPlan(options: {
   };
 }
 
+/** Records a deliberately undelivered final reply without its content. */
+function recordTelegramDroppedFinalReply(
+  recordRuntimeEvent:
+    | ((category: string, error: unknown, details?: Record<string, unknown>) => void)
+    | undefined,
+  phase: string,
+  turn: PendingTelegramTurn | undefined,
+  content: { text?: string; attachmentCount?: number },
+): void {
+  recordRuntimeEvent?.(
+    "delivery",
+    new Error("Telegram final reply was not delivered."),
+    {
+      phase,
+      hasTurn: !!turn,
+      hasThread: turn?.target?.threadId !== undefined,
+      textLength: content.text?.length ?? 0,
+      attachmentCount: content.attachmentCount ?? 0,
+    },
+  );
+}
+
 export function createTelegramAgentEndHook<
   TTurn extends PendingTelegramTurn,
   TContext,
@@ -1777,7 +1799,18 @@ export function createTelegramAgentEndHook<
     ctx: TContext,
     assistantOverride?: TelegramAgentEndAssistantResult,
   ): Promise<void> => {
-    if (deps.isSessionActive?.(ctx) === false) return;
+    if (deps.isSessionActive?.(ctx) === false) {
+      const activeTurn = deps.getActiveTurn();
+      if (activeTurn) {
+        recordTelegramDroppedFinalReply(
+          deps.recordRuntimeEvent,
+          "final-reply-session-inactive",
+          activeTurn,
+          { attachmentCount: activeTurn.queuedAttachments.length },
+        );
+      }
+      return;
+    }
     const turn = deps.getActiveTurn();
     const extractedAssistant = assistantOverride ?? (turn ? deps.extractAssistant(event.messages) : {});
     const assistant = deps.isAssistantAlreadyPublished?.(extractedAssistant)
@@ -1788,7 +1821,20 @@ export function createTelegramAgentEndHook<
     const scheduleDelivery = reservation?.schedule ?? deps.scheduleActiveTurnDelivery;
     try {
       await deps.loadConfig?.();
-      if (deps.isSessionActive?.(ctx) === false || deps.getActiveTurn() !== turn) return;
+      const sessionInactive = deps.isSessionActive?.(ctx) === false;
+      if (sessionInactive || deps.getActiveTurn() !== turn) {
+        if (hasPublication) {
+          recordTelegramDroppedFinalReply(
+            deps.recordRuntimeEvent,
+            sessionInactive
+              ? "final-reply-session-inactive"
+              : "final-reply-turn-replaced",
+            turn,
+            { text: assistant.text, attachmentCount: turn?.queuedAttachments.length },
+          );
+        }
+        return;
+      }
       await handleTelegramAgentEndRuntime({
         turn,
         assistant,
@@ -1872,9 +1918,32 @@ export async function handleTelegramAgentEndRuntime<
   const hasOutboundArtifacts =
     !!outboundReply?.voiceText || !!outboundReply?.voiceReplies?.length;
   const replyMarkup = outboundReply?.replyMarkup;
-  const isDeliveryActive = (): boolean =>
-    deps.isSessionActive?.() !== false &&
-    (!turn || deps.isTurnTransportActive?.(turn) !== false);
+  const hasPublishableContent =
+    !!finalText ||
+    hasOutboundArtifacts ||
+    (turn?.queuedAttachments.length ?? 0) > 0 ||
+    assistant.stopReason === "error";
+  let dropRecorded = false;
+  // The first failed fence that would lose content leaves one diagnostic event;
+  // without it a dropped final reply is indistinguishable from a sent one.
+  const isDeliveryActive = (): boolean => {
+    const sessionActive = deps.isSessionActive?.() !== false;
+    const transportActive =
+      !turn || deps.isTurnTransportActive?.(turn) !== false;
+    if (sessionActive && transportActive) return true;
+    if (!dropRecorded && hasPublishableContent) {
+      dropRecorded = true;
+      recordTelegramDroppedFinalReply(
+        deps.recordRuntimeEvent,
+        sessionActive
+          ? "final-reply-transport-inactive"
+          : "final-reply-session-inactive",
+        turn,
+        { text: finalText, attachmentCount: turn?.queuedAttachments.length },
+      );
+    }
+    return false;
+  };
   const preview = turn && !turn.guestQueryId ? deps.preparePreviewDelivery?.(isDeliveryActive) : undefined;
   const setPreviewPendingText = preview?.setPreviewPendingText ?? deps.setPreviewPendingText;
   const finalizeMarkdownPreview = preview?.finalizeMarkdownPreview ?? deps.finalizeMarkdownPreview;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carlitose86/pi-telegram-reactive",
-  "version": "0.1.0-next.0",
+  "version": "0.1.0-next.1",
   "private": false,
   "publishConfig": {
     "access": "public",