@llblab/pi-telegram 0.45.3 → 0.45.4

package/CHANGELOG.md

@@ -4,6 +4,10 @@
 
 ## Unreleased
 
+## 0.45.4: Draft Cadence Hotfix
+
+- `Draft Cadence`: Each preview segment now holds its first frame for one full two-second interval from its first visible text, so the opening draft is an accumulated passage instead of a single streamed word. Later frames keep the trailing cadence, message/turn rollover preserves the remaining interval and reopens the window, and sealing or final publication still cancels the pending timer; first frames no longer ship immediately.
+
 ## 0.45.3: Thread Display Names Hotfix
 
 - `Thread Display Names`: Settings again offers the dictionary naming mode as the second chooser between Letters and Directories. Names shows each Workspace's generated slot-letter palette word, such as `Anchor` for slot `A`; switching renames live tabs and fresh tabs start under the active projection. `profiles.<name>.threadDisplayMode` persists all three values, absent or invalid ones resolve to Letters, and Names works with legacy followers that predate `thread-display-mode-v1`.

package/docs/outbound.md

@@ -16,7 +16,7 @@ Projected blocks use `assistant.rendering` independently of voice policy. Rich m
 
 Assistant-message completion seals its preview state: queued follow-up drafts and late updates are suppressed. Native final delivery still waits for the already-issued draft request before sending the permanent answer, so an older draft is not deliberately allowed to overtake the final. Intermediate publication seals and drains its captured preview before sending permanent text. Preview rollover itself sends no permanent message: it carries the preceding delivery boundary and draft identity into the next state without holding the Pi message-start hook. The next draft waits for that publication to settle, including failure or cancellation. Active-turn final delivery captures its preview operations before entering the background queue: it drains only the originating draft, leaves a successor's preview untouched, and cannot wait for a successor publication queued behind itself. Delivery authority is rechecked after the captured flush; if the original preview has been replaced, ordinary final sending remains the queue's responsibility. This does not promise instant delivery or eliminate Telegram/client latency.
 
-Assistant previews use a two-second leading/trailing throttle per preview controller, with at most one request in flight. The first eligible snapshot sends immediately; changes inside the window replace pending text, and one trailing timer sends the latest safe snapshot without moving its deadline on every delta. Message/turn rollover preserves the remaining interval. Sealing, clearing, or replacing preview state cancels its timer; final publication drains only an already-issued request and never waits for the throttle deadline.
+Assistant previews use a two-second trailing throttle per preview controller, with at most one request in flight. Each preview segment holds its first frame for one full interval from its first visible text, so the opening frame is an accumulated passage instead of the first streamed word even when the previous cadence boundary has already passed (fresh turn, slow first token, or rollover after tool work); changes inside the window replace pending text, and one trailing timer sends the latest safe snapshot without moving its deadline on every delta. Message/turn rollover preserves the remaining interval and reopens the initial window for the next segment. Sealing, clearing, or replacing preview state cancels its timer; final publication drains only an already-issued request and never waits for the throttle deadline.
 
 The Bot API client does not replay draft snapshots through API retry backoff. After a retryable draft HTTP failure (`429` or `5xx`), it defers new draft requests for that bot/chat/thread using the existing `Retry-After` or default backoff delay; it stores a deadline, not a body or a background retry. A deferred update does not advance the preview's last-delivered text. Fresh updates can send after the deadline, while a sealed preview cannot resume. Different bots and thread targets have independent cooldowns; credential rotation for the same bot does not bypass its deadline. Permanent replies retain their existing retry policy. Already-issued requests and Telegram/client rendering can still delay visible completion.
 

package/lib/preview.ts

@@ -15,6 +15,9 @@ import { shouldSuppressPreviewForVoice } from "./voice.ts";
 
 const TELEGRAM_DRAFT_ID_MAX = 2_147_483_647;
 const TELEGRAM_DRAFT_PREVIEW_MAX_CHARS = 4096;
+// Native draft cadence: at most one frame per interval, and a fresh preview
+// segment holds its first frame for one full interval so the opening frame is
+// an accumulated passage rather than a single streamed word.
 const TELEGRAM_DRAFT_INTERVAL_MS = 2_000;
 
 export type TelegramDraftSupport = "unknown" | "supported";
@@ -90,6 +93,7 @@ export interface TelegramAssistantMessagePreviewUpdateDeps<TMessage> {
   createPreviewState: () => TelegramPreviewRuntimeState;
   canSend?: () => boolean;
   getMessageText: (message: TMessage) => string;
+  minDraftIntervalMs?: number;
   schedulePreviewFlush: (
     chatId: number,
     options?: { target?: TelegramTarget },
@@ -305,6 +309,7 @@ export function createTelegramAssistantPreviewRuntime<
       createPreviewState: controller.createState,
       canSend: deps.canSend,
       getMessageText: deps.getMessageText,
+      minDraftIntervalMs: TELEGRAM_DRAFT_INTERVAL_MS,
       schedulePreviewFlush: controller.scheduleFlush,
     }),
   };
@@ -466,9 +471,24 @@ export async function handleTelegramAssistantMessagePreviewUpdate<TMessage>(
     deps.setState(state);
   }
   if (state.sealed) return;
+  const hadVisibleText = state.pendingText.length > 0;
   state.pendingText = stripTelegramCommentMarkupForPreview(
     deps.getMessageText(message),
   );
+  // The first visible text of a preview segment opens an initial accumulation
+  // window, so the segment's first frame cannot ship as a single word even
+  // when the previous cadence boundary has already passed (fresh turn, slow
+  // first token, or message rollover after tool work). Later deltas keep the
+  // trailing deadline instead of sliding it on every update.
+  const interval = deps.minDraftIntervalMs ?? 0;
+  if (
+    interval > 0 &&
+    !hadVisibleText &&
+    !state.lastSentText &&
+    state.pendingText.length > 0
+  ) {
+    state.nextDraftAt = Math.max(state.nextDraftAt ?? 0, Date.now() + interval);
+  }
   deps.schedulePreviewFlush(turn.chatId, { target: turn.target });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.45.3",
+  "version": "0.45.4",
   "private": false,
   "publishConfig": {
     "access": "public"