Preserve Telegram message order between turns

Author: assistant-ngalaiko[bot]

packages/pilegram/src/renderer.ts

@@ -155,7 +155,7 @@ export class Renderer {
   }
 
   /** Finalize on agent_settled. `finalText` is the authoritative answer. */
-  onSettled(finalText: string | undefined) {
+  onSettled(finalText: string | undefined): Promise<void> {
     const answer = finalText && finalText.trim() !== "" ? finalText : this.acc;
     const counts = new Map(this.toolCounts);
     const elapsedMs = this.turnStartAt ? Date.now() - this.turnStartAt : 0;
@@ -175,14 +175,12 @@ export class Renderer {
     if (this.voiceMode) {
       // The Session sends this answer as a voice note; don't leave a provisional
       // text message behind while it does so.
-      void this.deletePreview(preview);
       this.log.info("finalize: voice-only (text not persisted)");
-      return;
+      return this.deletePreview(preview);
     }
     if (answer.trim() === "") {
-      void this.deletePreview(preview);
       this.log.info("finalize: empty (preview deleted)");
-      return;
+      return this.deletePreview(preview);
     }
 
     // Strip bidi-override / zero-width chars so a prompt-injected answer can't
@@ -209,7 +207,7 @@ export class Renderer {
       html: !!extra,
       preview: !!preview,
     });
-    void this.finalizePreview(preview, chunks, extra);
+    return this.finalizePreview(preview, chunks, extra);
   }
 
   /**

packages/pilegram/src/session.ts

@@ -64,6 +64,8 @@ export interface SessionOptions {
 
 export class Session {
   private busy = false;
+  /** Final Telegram writes from a settled turn; the next prompt waits for these. */
+  private settling?: Promise<void>;
   private voiceMode = false;
   private spokeThisTurn = false; // set if the agent sent a voice note via tg_send_voice this turn
   private readonly unsubscribe: () => void;
@@ -186,22 +188,31 @@ export class Session {
         break;
       case "agent_settled": {
         const finalText = this.agent.getLastAssistantText();
-        this.renderer.onSettled(finalText);
-        this.busy = false;
-        // A voice-only turn's text is spoken, never rendered to Telegram — don't
-        // record it as the last-rendered answer, or reconcile would suppress the
-        // legitimate text repost if we crash before the voice note is sent.
-        this.onFinalized?.(this.voiceMode ? undefined : finalText);
-        // Voice mode: speak the answer as a voice note — unless the agent already
-        // sent one itself via tg_send_voice, which would double up.
-        if (
-          this.voiceMode &&
-          this.voice &&
-          !this.spokeThisTurn &&
-          finalText &&
-          finalText.trim() !== ""
-        )
-          void this.speak(finalText);
+        // Do not let the next prompt start writing until this turn has claimed
+        // its final Telegram writes. Otherwise a fast next turn can enqueue its
+        // preview before this turn finishes replacing its preview.
+        this.settling = (async () => {
+          await this.renderer.onSettled(finalText);
+          // A voice-only turn's text is spoken, never rendered to Telegram — don't
+          // record it as the last-rendered answer, or reconcile would suppress the
+          // legitimate text repost if we crash before the voice note is sent.
+          this.onFinalized?.(this.voiceMode ? undefined : finalText);
+          // Voice mode: speak the answer as a voice note — unless the agent already
+          // sent one itself via tg_send_voice, which would double up.
+          if (
+            this.voiceMode &&
+            this.voice &&
+            !this.spokeThisTurn &&
+            finalText &&
+            finalText.trim() !== ""
+          )
+            await this.speak(finalText);
+        })()
+          .catch((e) => this.log.error("turn finalization failed", errFields(e)))
+          .finally(() => {
+            this.settling = undefined;
+            this.busy = false;
+          });
         break;
       }
       default:
@@ -220,14 +231,22 @@ export class Session {
   async handlePrompt(
     text: string,
     opts?: { images?: ImageContent[]; messageId?: number; speak?: boolean },
-  ) {
+  ): Promise<void> {
     const images = opts?.images;
     if (opts?.messageId !== undefined) {
       if (this.turn) this.turn.messageId = opts.messageId; // for tg_react
       this.messageLog?.add(opts.messageId, "user", text); // for the context-injected id table
     }
 
     if (this.busy) {
+      // `agent_settled` fires before its final preview edit has necessarily
+      // reached Telegram. This is a completed turn, not steering: wait for its
+      // writes, then start a fresh turn in chronological order.
+      if (this.settling) {
+        this.log.info("waiting for prior turn finalization");
+        await this.settling;
+        return this.handlePrompt(text, opts);
+      }
       this.log.info("steering into running turn");
       await this.agent.steer(text, images);
       return;
@@ -244,7 +263,9 @@ export class Session {
         this.renderer.onError(e);
       })
       .finally(() => {
-        this.busy = false;
+        // agent_settled owns the transition to idle while final Telegram writes
+        // are pending. For failures that never settle, release the session here.
+        if (!this.settling) this.busy = false;
       });
   }