switchroom 0.13.13 → 0.13.15

package/telegram-plugin/gateway/gateway.ts

@@ -76,6 +76,7 @@ import {
 import { emitRuntimeMetric } from '../runtime-metrics.js'
 import { classifyInbound } from '../inbound-classifier.js'
 import * as silencePoke from '../silence-poke.js'
+import * as pendingProgress from '../pending-work-progress.js'
 import { writeSilentEndState, clearSilentEndState, recordUndeliveredTurnEnd } from '../silent-end.js'
 import { isFinalAnswerReply } from '../final-answer-detect.js'
 import { createAnswerStream, type AnswerStreamHandle } from '../answer-stream.js'
@@ -2854,6 +2855,42 @@ const STREAM_THROTTLE_MS_OVERRIDE: number | undefined = (() => {
   return Number.isFinite(n) && n >= 0 ? n : undefined
 })()
 const TURN_FLUSH_SAFETY_ENABLED = isTurnFlushSafetyEnabled()
+
+// #869-Phase1 / openclaw-pattern. When SET, the answer-lane stream
+// (telegram-plugin/answer-stream.ts) renders the model's transcript
+// text as a USER-VISIBLE edit-in-place message instead of writing to
+// Telegram's invisible compose-box draft (which is the default and
+// supports the #1664 "retract + re-prompt" contract). With this flag
+// on:
+//   1. createAnswerStream is instantiated without `sendMessageDraft`,
+//      so it falls back to `sendMessage` + `editMessageText` for a
+//      real chat-timeline message (`answer-stream.ts:212-214`).
+//   2. minInitialChars is set to 1 — the first text chunk pushes a
+//      visible message immediately (TTFO under 5s for short turns).
+//   3. At turn_end, if the model never called reply / stream_reply
+//      AND the streamed message has substantive captured text, the
+//      gateway DOES NOT retract (which would delete a user-visible
+//      message the user has been reading live); it calls
+//      `stream.stop()` to freeze the current text as the final
+//      answer, records the message in dedup + history, and marks
+//      `turn.finalAnswerDelivered = true` so the #1664 silent-end
+//      re-prompt does not fire. Turn-flush is suppressed for this
+//      branch — its job (deliver captured text) is structurally
+//      already done by the visible stream.
+//   4. The reply-tool / stream_reply path is unchanged — when the
+//      model uses an explicit reply tool the prior streamed message
+//      is retracted (delete) and the reply takes over as before.
+// Trade-off: a stream-as-final-answer turn does NOT push a device
+// notification (Telegram does not notify on edits, and we choose
+// not to send a duplicate fresh message for the ping). For short
+// turns where the user is actively watching, this is the right
+// shape — they see the answer materialise live. For longer waits,
+// the cross-turn pending-progress system (#1445/#1669) is the
+// canonical surface and DOES ping at the appropriate boundaries.
+// Default OFF; flip per-agent via env to canary the new behaviour.
+const ANSWER_STREAM_VISIBLE_ENABLED =
+  process.env.SWITCHROOM_VISIBLE_ANSWER_STREAM === '1'
+  || process.env.SWITCHROOM_VISIBLE_ANSWER_STREAM === 'true'
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const progressDriver: any = null
 const unpinProgressCardForChat: ((chatId: string, threadId: number | undefined) => void) | null = null
@@ -3149,6 +3186,7 @@ silencePoke.startTimer({
     // Drop silence-poke state and clear turn-active so the next inbound
     // for this chat starts a fresh turn instead of queueing forever.
     silencePoke.endTurn(fbKey)
+    pendingProgress.noteTurnEnd(fbKey)
     purgeReactionTracking(fbKey)
     // Defense-in-depth: the fallback's purgeReactionTracking above
     // clears the canonical statusKey(chatId, threadId) for fbKey
@@ -3206,6 +3244,34 @@ silencePoke.startTimer({
   },
 })
 
+// #1445 cross-turn pending-async ambient. When a turn ends after the
+// model dispatched background async work (Agent / Task / Bash run-in-
+// background) and the model has stopped speaking, keep editing the
+// model's last reply in place at 60s intervals so the user sees
+// ambient liveness during the wait. Edits are silent, never spawn a
+// new pinged message, and stop the moment the user re-engages or the
+// model synthesises a handback. The full design rationale lives in
+// `pending-work-progress.ts`'s header docblock. Kill switch:
+// `SWITCHROOM_DISABLE_PENDING_PROGRESS=1`.
+pendingProgress.startTimer({
+  editMessage: async (ctx) => {
+    await swallowingApiCall(
+      () =>
+        lockedBot.api.editMessageText(
+          ctx.chatId,
+          ctx.messageId,
+          ctx.newText,
+        ),
+      {
+        chat_id: ctx.chatId,
+        verb: 'pending-progress-edit',
+        ...(ctx.threadId != null ? { threadId: ctx.threadId } : {}),
+      },
+    )
+  },
+  emitMetric: (event) => emitRuntimeMetric(event),
+})
+
 // Per-agent buffer for synthetic inbounds the gateway couldn't deliver
 // because the bridge wasn't connected at send-time. Drained on
 // bridge-register so a fresh client picks up missed wake-ups before
@@ -3578,6 +3644,22 @@ const ipcServer: IpcServer = createIpcServer({
             label.length > 0 ? label : null,
             Date.now(),
           )
+          // #1445 cross-turn pending-async ambient. Mark the chat as
+          // having dispatched background work this turn so a turn_end
+          // that follows activates the edit-in-place ambient line.
+          // Covers `Agent` / `Task` (the harness-managed async path
+          // — handback channel turn clears it) and `Bash` with
+          // run_in_background:true (model is expected to poll
+          // BashOutput; the ambient ticks until next inbound or the
+          // 30-min budget cap).
+          const evInput = ev.input as { run_in_background?: boolean } | undefined
+          if (
+            ev.toolName === 'Agent'
+            || ev.toolName === 'Task'
+            || (ev.toolName === 'Bash' && evInput?.run_in_background === true)
+          ) {
+            pendingProgress.noteAsyncDispatch(key)
+          }
         }
       } else if (ev.kind === 'tool_result') {
         // #1292: drain the in-flight entry. Idempotent on unknown ids
@@ -4391,6 +4473,22 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
     }
   }
 
+  // #1445 cross-turn pending-async ambient. Capture the last text
+  // chunk as the anchor — if this turn ends with a pending async
+  // dispatch, the framework edits THIS message in place every 60s
+  // with a `— still working (Nm)` suffix until the user re-engages.
+  // Multi-chunk replies: anchor is the LAST chunk (edits append to
+  // the visually-trailing message; earlier chunks are left intact).
+  if (sentIds.length === chunks.length && chunks.length > 0) {
+    const anchorMsgId = sentIds[chunks.length - 1]
+    if (typeof anchorMsgId === 'number') {
+      pendingProgress.noteOutbound(statusKey(chat_id, threadId), {
+        messageId: anchorMsgId,
+        text: chunks[chunks.length - 1],
+      })
+    }
+  }
+
   // #273: when files is 2-10 photos, batch them into a single
   // sendMediaGroup album rather than N separate sendPhoto calls. The
   // user's device fires one notification for the album instead of N
@@ -4715,6 +4813,15 @@ async function executeStreamReply(args: Record<string, unknown>): Promise<unknow
     const sChatId = args.chat_id as string
     const sThreadId = args.message_thread_id != null ? Number(args.message_thread_id) : undefined
     outboundDedup.record(sChatId, sThreadId, args.text as string, Date.now())
+    // #1445 cross-turn pending-async ambient. The terminal stream_reply
+    // (done=true) is the user-visible anchor for any cross-turn wait
+    // that follows. Capture it so if this turn ends with a pending
+    // async dispatch, the framework edits THIS message in place at
+    // intervals.
+    pendingProgress.noteOutbound(statusKey(sChatId, sThreadId), {
+      messageId: result.messageId,
+      text: args.text as string,
+    })
   }
   // #1664 — mark the turn's final answer as delivered. For stream_reply a
   // call with done=true IS the final answer by definition (the model
@@ -5728,6 +5835,25 @@ function handleSessionEvent(ev: SessionEvent): void {
       // Drain any orphaned typing-wrap entries left over from a crashed
       // prior turn before resetting focus.
       typingWrapper.drainAll()
+      if (ev.chatId) {
+        // #1445 cross-turn pending-async ambient — backstop for the
+        // `handleInbound` path's `clearPending('inbound')`. The
+        // inbound path covers real user messages, but synthesised
+        // wakes (subagent-handback channel turn, cron fires, vault
+        // grant resumes, restart markers) push directly to
+        // `pendingInboundBuffer` and bypass `handleInbound`. The
+        // `enqueue` session-event fires for EVERY fresh turn atom
+        // regardless of source — clearing here drops any prior turn's
+        // ambient before the new turn's `noteOutbound` lands. The
+        // call is idempotent so it's safe to fire in addition to the
+        // inbound-path clear (for the real-inbound case, this is a
+        // no-op because state was already deleted by then).
+        const enqThreadId = ev.threadId != null ? Number(ev.threadId) : undefined
+        pendingProgress.clearPending(
+          statusKey(ev.chatId, enqThreadId),
+          'handback',
+        )
+      }
       if (ev.chatId) {
         // Issue #195: if a previous turn left an answer-lane stream open
         // (rapid steer/queue), force it to a new generation so its in-flight
@@ -5896,7 +6022,13 @@ function handleSessionEvent(ev: SessionEvent): void {
             chatId: turn.sessionChatId,
             isPrivateChat: turn.isDm,
             threadId: turn.sessionThreadId,
-            sendMessageDraft: sendMessageDraftFn,
+            // #869-Phase1 visible-answer-stream: omit the draft API so
+            // the lane uses the real sendMessage / editMessageText path
+            // and edits a user-visible chat-timeline message instead
+            // of the invisible compose-box draft.
+            ...(ANSWER_STREAM_VISIBLE_ENABLED
+              ? { minInitialChars: 1 }
+              : { sendMessageDraft: sendMessageDraftFn }),
             // #1075: route through robustApiCall so flood-wait,
             // benign-400, and THREAD_NOT_FOUND are handled uniformly
             // instead of crashing the answer-stream loop on a deleted
@@ -6045,6 +6177,7 @@ function handleSessionEvent(ev: SessionEvent): void {
         // full message above). Match the pattern used at the regular
         // turn-end path (line ~5039) and the wedged-turn path (~5290).
         silencePoke.endTurn(ceKey)
+        pendingProgress.noteTurnEnd(ceKey)
         // Issue #195: tear down the answer-lane stream on context-exhaustion
         // bail-out. The user is being told the session needs /restart, so any
         // partially-streamed answer would be misleading.
@@ -6098,20 +6231,71 @@ function handleSessionEvent(ev: SessionEvent): void {
       // (regression for short no-tool replies). Order matters here: this
       // call must come before the retract/null block.
       preambleSuppressor.flushNow()
-      // #656: always retract the answer-lane stream at turn_end. Turn-flush
-      // (gateway.ts ~3475) is the sole canonical emitter for no-reply turns —
-      // it runs markdownToHtml and records to outboundDedup. Materializing
-      // here would race turn-flush and post raw model text (no HTML conv).
+      // #656: by default we ALWAYS retract the answer-lane stream at
+      // turn_end. Turn-flush is the canonical emitter for no-reply
+      // turns; materialising here would race it and post raw model
+      // text (no HTML conv).
+      //
+      // #869-Phase1 override: when `ANSWER_STREAM_VISIBLE_ENABLED` is
+      // on, the stream is rendering a USER-VISIBLE message in the
+      // chat timeline. Retracting (delete) destroys content the user
+      // has been reading live — the worst possible UX flicker. So
+      // when the stream is the de-facto final answer (model never
+      // called reply, captured text is substantive) we instead call
+      // `stream.stop()` to freeze it as the final state, record the
+      // outbound for history + dedup, mark the turn answered, and
+      // suppress the turn-flush IIFE downstream.
+      let streamFinalizedAsAnswer = false
       if (turn?.answerStream != null) {
         const stream = turn.answerStream
-        turn.answerStream = null
-        void stream.retract().catch((err) => {
+        const streamedMsgId = stream.messageId()
+        const streamedFinalText = turn.capturedText.join('').trim()
+        if (
+          ANSWER_STREAM_VISIBLE_ENABLED
+          && !turn.replyCalled
+          && streamedMsgId != null
+          && streamedFinalText.length > 0
+        ) {
+          turn.answerStream = null
+          stream.stop()
+          streamFinalizedAsAnswer = true
+          turn.finalAnswerDelivered = true
+          // Record as canonical outbound so retries dedup against it
+          // and the SQLite history can surface it. Mirrors the
+          // hooks turn-flush + reply both run.
+          try {
+            outboundDedup.record(
+              turn.sessionChatId,
+              turn.sessionThreadId,
+              streamedFinalText,
+              Date.now(),
+            )
+          } catch { /* best-effort */ }
+          if (HISTORY_ENABLED) {
+            try {
+              recordOutbound({
+                chat_id: turn.sessionChatId,
+                thread_id: turn.sessionThreadId ?? null,
+                message_ids: [streamedMsgId],
+                texts: [streamedFinalText],
+              })
+            } catch { /* best-effort */ }
+          }
           process.stderr.write(
-            `telegram gateway: answer-stream retract failed: ${
-              err instanceof Error ? err.message : String(err)
-            }\n`,
+            `telegram gateway: answer-stream finalized as answer ` +
+            `chat=${turn.sessionChatId} msg=${streamedMsgId} ` +
+            `chars=${streamedFinalText.length}\n`,
           )
-        })
+        } else {
+          turn.answerStream = null
+          void stream.retract().catch((err) => {
+            process.stderr.write(
+              `telegram gateway: answer-stream retract failed: ${
+                err instanceof Error ? err.message : String(err)
+              }\n`,
+            )
+          })
+        }
       }
       if (turn == null) return
       const chatId = turn.sessionChatId
@@ -6123,12 +6307,19 @@ function handleSessionEvent(ev: SessionEvent): void {
       // surface to recover from. The decideTurnFlush 'empty-text'
       // path now relies on capturedText alone.
 
-      const flushDecision = decideTurnFlush({
-        chatId: turn.sessionChatId,
-        replyCalled: turn.replyCalled,
-        capturedText: turn.capturedText,
-        flushEnabled: TURN_FLUSH_SAFETY_ENABLED,
-      })
+      // #869-Phase1: when the answer-stream finalised as the answer
+      // above, skip the turn-flush IIFE entirely — its job (deliver
+      // captured text) is already done by the visible stream, and
+      // running it would race a duplicate fresh-sendMessage against
+      // the user-visible edited message.
+      const flushDecision = streamFinalizedAsAnswer
+        ? ({ kind: 'skip', reason: 'reply-called' } as ReturnType<typeof decideTurnFlush>)
+        : decideTurnFlush({
+            chatId: turn.sessionChatId,
+            replyCalled: turn.replyCalled,
+            capturedText: turn.capturedText,
+            flushEnabled: TURN_FLUSH_SAFETY_ENABLED,
+          })
       if (flushDecision.kind === 'skip' && flushDecision.reason !== 'reply-called') {
         process.stderr.write(
           `telegram gateway: turn-flush skipped — reason=${flushDecision.reason}\n`,
@@ -6230,6 +6421,7 @@ function handleSessionEvent(ev: SessionEvent): void {
           try { removeTurnActiveMarker(STATE_DIR) } catch { /* best-effort */ }
           signalTracker.clear(tKey)
           silencePoke.endTurn(tKey)
+          pendingProgress.noteTurnEnd(tKey)
         }
         lastPtyPreviewByChat.delete(statusKey(chatId, threadId))
         pendingPtyPartial = null
@@ -6304,6 +6496,7 @@ function handleSessionEvent(ev: SessionEvent): void {
           const tKey = statusKey(chatId, threadId)
           signalTracker.clear(tKey)
           silencePoke.endTurn(tKey)
+          pendingProgress.noteTurnEnd(tKey)
         }
 
         void (async () => {
@@ -6550,6 +6743,7 @@ function handleSessionEvent(ev: SessionEvent): void {
         }
         signalTracker.clear(tKey)
         silencePoke.endTurn(tKey)
+        pendingProgress.noteTurnEnd(tKey)
       }
       lastPtyPreviewByChat.delete(statusKey(chatId, threadId))
       pendingPtyPartial = null
@@ -7772,6 +7966,18 @@ async function handleInbound(
         // the framework can nudge the model if it goes quiet past the
         // soft / firm thresholds.
         silencePoke.startTurn(statusKey(chat_id, messageThreadId), Date.now())
+        // #1445 cross-turn pending-async ambient. A new turn starting
+        // (user inbound, synthesised wake, or handback channel) is the
+        // signal that the model is about to re-engage — clear any
+        // pending-progress edits anchored to the *prior* turn's
+        // outbound so the framework stops talking over the new turn.
+        // clearPending drops the per-key state outright, so the new
+        // turn's `tool_use(Agent|Task|Bash bg)` + outbound capture
+        // afresh via `noteAsyncDispatch` / `noteOutbound`.
+        pendingProgress.clearPending(
+          statusKey(chat_id, messageThreadId),
+          'inbound',
+        )
         // Human-feel UX: hold a continuous `typing…` indicator for the
         // WHOLE turn, not just the split-second a reply is transmitted.
         // A person you message shows as typing the entire time they