switchroom 0.13.26 → 0.13.27

package/telegram-plugin/subagent-watcher.ts

@@ -114,6 +114,14 @@ export interface WorkerEntry {
    * narrative line.
    */
   lastResultText: string
+  /**
+   * Last bucket index for which an `onProgress` callback was fired for
+   * this sub-agent (#1720). Null until the first envelope. The gateway
+   * owns the actual decision via `decideSubagentProgress`; this field
+   * persists the cursor across `sub_agent_text` events on the same
+   * entry so the watcher doesn't re-fire within the same bucket window.
+   */
+  lastProgressBucketIdx: number | null
   /**
    * Most recent tool call observed on this sub-agent's JSONL tail —
    * tool name + sanitised arg for fleet-row display (P0 of #662). Null
@@ -281,6 +289,23 @@ export interface SubagentWatcherConfig {
      *  `subagent_handback` inbound. */
     resultText: string
   }) => void
+  /**
+   * #1720: fires on every `sub_agent_text` event for a running
+   * sub-agent. The gateway decides whether to materialise a
+   * `subagent_progress` envelope via `decideSubagentProgress` (pure,
+   * bucket-deterministic); the watcher just surfaces the cue.
+   * `setBucketIdx` writes back the per-entry cursor so a same-bucket
+   * re-fire is suppressed. Foreground vs background classification is
+   * the gateway's call.
+   */
+  onProgress?: (args: {
+    agentId: string
+    description: string
+    latestSummary: string
+    elapsedMs: number
+    prevBucketIdx: number | null
+    setBucketIdx: (b: number) => void
+  }) => void
   /** `Date.now` override for tests. */
   now?: () => number
   /** `setInterval` override for tests. */
@@ -483,6 +508,21 @@ export function readSubTail(
    *  the clerk agent logged 540k ENOENT lines in 3 days (30/sec
    *  sustained) AND leaked one fs.watch FD per stranded entry. */
   onFileVanished?: (agentId: string, code: 'ENOENT' | 'EACCES') => void,
+  /** Fires on every `sub_agent_text` event for a running sub-agent
+   *  (#1720). The gateway decides whether to materialise a progress
+   *  envelope via `decideSubagentProgress` — pure decision, watcher
+   *  just surfaces the cue. `latestSummary` is the narrative text;
+   *  `elapsedMs` is `now - entry.dispatchedAt`; `prevBucketIdx` is
+   *  `entry.lastProgressBucketIdx` (gateway calls `setBucketIdx` on a
+   *  successful deliver so a same-bucket re-fire is suppressed). */
+  onProgress?: (args: {
+    agentId: string
+    description: string
+    latestSummary: string
+    elapsedMs: number
+    prevBucketIdx: number | null
+    setBucketIdx: (b: number) => void
+  }) => void,
 ): void {
   try {
     const stat = fs.statSync(entry.filePath)
@@ -620,6 +660,26 @@ export function readSubTail(
           // args or file content — consistent with the watcher's
           // "descriptions only" privacy posture.
           entry.lastResultText = ev.text.trim().slice(0, SUBAGENT_RESULT_TEXT_MAX)
+          // #1720: surface a progress cue for the gateway. Only fire
+          // while the entry is still running and not historical — a
+          // terminal entry's last narrative line is the handback
+          // payload, not a mid-flight progress nudge.
+          if (onProgress != null && entry.state === 'running' && !entry.historical) {
+            try {
+              onProgress({
+                agentId: entry.agentId,
+                description: entry.description,
+                latestSummary: entry.lastResultText,
+                elapsedMs: now - entry.dispatchedAt,
+                prevBucketIdx: entry.lastProgressBucketIdx,
+                setBucketIdx: (b: number) => {
+                  entry.lastProgressBucketIdx = b
+                },
+              })
+            } catch (cbErr) {
+              log?.(`subagent-watcher: onProgress callback error ${entry.agentId}: ${(cbErr as Error).message}`)
+            }
+          }
         } else if (ev.kind === 'sub_agent_turn_end') {
           if (entry.state === 'running') {
             entry.state = 'done'
@@ -802,6 +862,7 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
       stallTerminalSynthesised: false,
       lastSummaryLine: '',
       lastResultText: '',
+      lastProgressBucketIdx: null,
       lastTool: null,
       historical: isHistorical,
     }
@@ -832,7 +893,7 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
     // Initial read
     readSubTail(entry, tail, n, (desc) => {
       log?.(`subagent-watcher: description updated for ${agentId}: ${desc}`)
-    }, fs, log, db, parentStateDir, config.onUnstall)
+    }, fs, log, db, parentStateDir, config.onUnstall, undefined, config.onProgress)
 
     // If the JSONL already contained a turn_end at registration time
     // (file written-then-watched), fire the state-transition + completion
@@ -863,7 +924,7 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
         if (!entry || !t) return
         readSubTail(entry, t, nowFn(), (desc) => {
           log?.(`subagent-watcher: description updated for ${agentId}: ${desc}`)
-        }, fs, log, db, parentStateDir, config.onUnstall, cleanupTerminalAgent)
+        }, fs, log, db, parentStateDir, config.onUnstall, cleanupTerminalAgent, config.onProgress)
         maybySendStateTransition(agentId)
       })
     } catch (err) {
@@ -1201,7 +1262,7 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
       if (!tail) continue
       readSubTail(entry, tail, n, (desc) => {
         log?.(`subagent-watcher: description updated for ${agentId}: ${desc}`)
-      }, fs, log, db, parentStateDir, config.onUnstall, cleanupTerminalAgent)
+      }, fs, log, db, parentStateDir, config.onUnstall, cleanupTerminalAgent, config.onProgress)
       maybySendStateTransition(agentId)
     }
 

package/telegram-plugin/tests/gateway-disconnect-flush.test.ts

@@ -20,7 +20,9 @@ import { describe, it, expect, vi } from 'vitest'
 import { flushOnAgentDisconnect } from '../gateway/disconnect-flush.js'
 
 interface FakeCtrl {
-  setDone: () => void
+  // #1713: disconnect-flush now routes through finalize() — single
+  // terminal path for the status-reaction controller.
+  finalize: (reason?: 'done' | 'error') => void
 }
 interface FakeStream {
   isFinal: () => boolean
@@ -37,8 +39,8 @@ function makeDeps(agentName: string | null) {
   const log = vi.fn()
 
   const activeStatusReactions = new Map<string, FakeCtrl>([
-    ['chat1:thr1:msg1', { setDone: setDoneA }],
-    ['chat2:thr2:msg2', { setDone: setDoneB }],
+    ['chat1:thr1:msg1', { finalize: setDoneA }],
+    ['chat2:thr2:msg2', { finalize: setDoneB }],
   ])
   const activeReactionMsgIds = new Map<string, { chatId: string; messageId: number }>([
     ['chat1:thr1:msg1', { chatId: 'chat1', messageId: 1 }],

package/telegram-plugin/tests/inbound-spool-progress.test.ts

@@ -0,0 +1,213 @@
+/**
+ * #1720 — extensions to inbound-spool for the progress envelope.
+ *
+ * Three behaviours pinned here that the existing spool tests don't
+ * cover:
+ *
+ *   1. spoolId for `subagent_progress` is bucket-deterministic — two
+ *      envelopes for the same (jsonl id, bucket idx) collapse to ONE
+ *      live entry regardless of ts.
+ *   2. `liveEntries()` skips entries whose `meta.expiresAt` has
+ *      passed (stale progress is worse than no progress).
+ *   3. `dropMatching(predicate)` tombstones live entries by spool id
+ *      prefix — the handback path uses this to sweep stale progress
+ *      envelopes for a sub-agent at the moment its handback is queued.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  createInboundSpool,
+  spoolId,
+  type InboundSpoolFsSeam,
+} from '../gateway/inbound-spool.js'
+import type { InboundMessage } from '../gateway/ipc-protocol.js'
+
+function progressMsg(over: {
+  jsonlId: string
+  bucketIdx: number
+  ts?: number
+  chatId?: string
+  expiresAt?: number
+}): InboundMessage {
+  const ts = over.ts ?? 1_000_000
+  const meta: Record<string, string> = {
+    source: 'subagent_progress',
+    subagent_jsonl_id: over.jsonlId,
+    bucket_idx: String(over.bucketIdx),
+  }
+  if (over.expiresAt != null) meta.expiresAt = String(over.expiresAt)
+  return {
+    type: 'inbound',
+    chatId: over.chatId ?? 'c1',
+    messageId: ts,
+    user: 'subagent-watcher',
+    userId: 0,
+    ts,
+    text: 'progress envelope',
+    meta,
+  }
+}
+
+function fakeFs(): InboundSpoolFsSeam {
+  const files = new Map<string, string>()
+  return {
+    appendFileSync: (p, d) => files.set(p, (files.get(p) ?? '') + d),
+    readFileSync: (p) => files.get(p) ?? '',
+    writeFileSync: (p, d) => files.set(p, d),
+    renameSync: (from, to) => {
+      files.set(to, files.get(from) ?? '')
+      files.delete(from)
+    },
+    existsSync: (p) => files.has(p),
+    statSizeSync: (p) => Buffer.byteLength(files.get(p) ?? ''),
+  }
+}
+
+const PATH = '/state/agent/telegram/inbound-spool.jsonl'
+
+describe('spoolId — subagent_progress branch (#1720)', () => {
+  it('two progress envelopes for the same (jsonl id, bucket idx) have IDENTICAL ids', () => {
+    const a = spoolId(progressMsg({ jsonlId: 'j1', bucketIdx: 2, ts: 1000 }))
+    const b = spoolId(progressMsg({ jsonlId: 'j1', bucketIdx: 2, ts: 9999 }))
+    expect(a).toBe('s:progress:j1:2')
+    expect(a).toBe(b)
+  })
+
+  it('different bucket idx → different id', () => {
+    expect(
+      spoolId(progressMsg({ jsonlId: 'j1', bucketIdx: 1 })),
+    ).not.toBe(spoolId(progressMsg({ jsonlId: 'j1', bucketIdx: 2 })))
+  })
+
+  it('different jsonl id → different id', () => {
+    expect(
+      spoolId(progressMsg({ jsonlId: 'j1', bucketIdx: 1 })),
+    ).not.toBe(spoolId(progressMsg({ jsonlId: 'j2', bucketIdx: 1 })))
+  })
+})
+
+describe('inbound-spool — progress envelopes coalesce by bucket', () => {
+  it('three puts for the same (jsonl id, bucket idx) yield ONE live entry', () => {
+    const fs = fakeFs()
+    const s = createInboundSpool({ path: PATH, fs })
+    expect(s.put('worker', progressMsg({ jsonlId: 'j1', bucketIdx: 1, ts: 1000 }))).toBe(true)
+    expect(s.put('worker', progressMsg({ jsonlId: 'j1', bucketIdx: 1, ts: 2000 }))).toBe(false)
+    expect(s.put('worker', progressMsg({ jsonlId: 'j1', bucketIdx: 1, ts: 3000 }))).toBe(false)
+    expect(s.liveCount()).toBe(1)
+  })
+
+  it('a fresh spool over the same file still sees ONE live entry (restart-safe coalesce)', () => {
+    const fs = fakeFs()
+    const s1 = createInboundSpool({ path: PATH, fs })
+    s1.put('worker', progressMsg({ jsonlId: 'j1', bucketIdx: 1, ts: 1000 }))
+    s1.put('worker', progressMsg({ jsonlId: 'j1', bucketIdx: 1, ts: 2000 }))
+    const s2 = createInboundSpool({ path: PATH, fs })
+    expect(s2.liveCount()).toBe(1)
+    expect(s2.liveEntries()[0].msg.meta.subagent_jsonl_id).toBe('j1')
+  })
+
+  it('successive buckets DO NOT collapse', () => {
+    const fs = fakeFs()
+    const s = createInboundSpool({ path: PATH, fs })
+    s.put('worker', progressMsg({ jsonlId: 'j1', bucketIdx: 1 }))
+    s.put('worker', progressMsg({ jsonlId: 'j1', bucketIdx: 2 }))
+    s.put('worker', progressMsg({ jsonlId: 'j1', bucketIdx: 3 }))
+    expect(s.liveCount()).toBe(3)
+  })
+})
+
+describe('inbound-spool — TTL filter on liveEntries (#1720)', () => {
+  it('an entry whose expiresAt is in the past is OMITTED from liveEntries', () => {
+    const fs = fakeFs()
+    let t = 1_000_000
+    const s = createInboundSpool({ path: PATH, fs, now: () => t })
+    // expiresAt = 1_002_000 — within window at put-time
+    s.put('worker', progressMsg({ jsonlId: 'j1', bucketIdx: 1, ts: t, expiresAt: 1_002_000 }))
+    expect(s.liveEntries()).toHaveLength(1)
+    expect(s.liveCount()).toBe(1) // raw count includes it
+    // Advance clock past expiry
+    t = 1_010_000
+    expect(s.liveEntries()).toHaveLength(0)
+    // liveCount is the raw map size — TTL is a read-time filter.
+    expect(s.liveCount()).toBe(1)
+  })
+
+  it('entries without expiresAt are not affected (handback envelopes stay live)', () => {
+    const fs = fakeFs()
+    let t = 1_000_000
+    const s = createInboundSpool({ path: PATH, fs, now: () => t })
+    s.put('worker', {
+      type: 'inbound',
+      chatId: 'c1',
+      messageId: 999,
+      user: 'x',
+      userId: 0,
+      ts: t,
+      text: 'handback',
+      meta: { source: 'subagent_handback' },
+    })
+    t = 9_000_000_000
+    expect(s.liveEntries()).toHaveLength(1)
+  })
+
+  it('a non-numeric or empty expiresAt is treated as "no expiry"', () => {
+    const fs = fakeFs()
+    let t = 1_000_000
+    const s = createInboundSpool({ path: PATH, fs, now: () => t })
+    s.put('worker', {
+      type: 'inbound',
+      chatId: 'c1',
+      messageId: 1,
+      user: 'x',
+      userId: 0,
+      ts: t,
+      text: 'x',
+      meta: { source: 'subagent_progress', subagent_jsonl_id: 'j1', bucket_idx: '1', expiresAt: '' },
+    })
+    s.put('worker', {
+      type: 'inbound',
+      chatId: 'c1',
+      messageId: 2,
+      user: 'x',
+      userId: 0,
+      ts: t,
+      text: 'x',
+      meta: { source: 'subagent_progress', subagent_jsonl_id: 'j2', bucket_idx: '1', expiresAt: 'not-a-number' },
+    })
+    t = 9_000_000_000
+    expect(s.liveEntries()).toHaveLength(2)
+  })
+})
+
+describe('inbound-spool — dropMatching (#1720 handback sweep)', () => {
+  it('drops every live entry whose id matches the predicate', () => {
+    const fs = fakeFs()
+    const s = createInboundSpool({ path: PATH, fs })
+    s.put('worker', progressMsg({ jsonlId: 'j1', bucketIdx: 1 }))
+    s.put('worker', progressMsg({ jsonlId: 'j1', bucketIdx: 2 }))
+    s.put('worker', progressMsg({ jsonlId: 'j2', bucketIdx: 1 }))
+    expect(s.liveCount()).toBe(3)
+    const dropped = s.dropMatching((id) => id.startsWith('s:progress:j1:'))
+    expect(dropped).toBe(2)
+    expect(s.liveCount()).toBe(1)
+    expect(s.liveEntries()[0].msg.meta.subagent_jsonl_id).toBe('j2')
+  })
+
+  it('a drop survives across a restart (tombstoned in the log)', () => {
+    const fs = fakeFs()
+    const s1 = createInboundSpool({ path: PATH, fs })
+    s1.put('worker', progressMsg({ jsonlId: 'j1', bucketIdx: 1 }))
+    s1.put('worker', progressMsg({ jsonlId: 'j1', bucketIdx: 2 }))
+    expect(s1.dropMatching((id) => id.startsWith('s:progress:j1:'))).toBe(2)
+    const s2 = createInboundSpool({ path: PATH, fs })
+    expect(s2.liveCount()).toBe(0)
+  })
+
+  it('an empty match set is a no-op (returns 0)', () => {
+    const fs = fakeFs()
+    const s = createInboundSpool({ path: PATH, fs })
+    s.put('worker', progressMsg({ jsonlId: 'j1', bucketIdx: 1 }))
+    expect(s.dropMatching((id) => id.startsWith('s:progress:nope:'))).toBe(0)
+    expect(s.liveCount()).toBe(1)
+  })
+})

package/telegram-plugin/tests/inbound-spool.test.ts

@@ -67,6 +67,68 @@ describe('spoolId — stable dedup key', () => {
     const b = spoolId(msg({ messageId: 0, meta: { source: 'cron' }, ts: 100 }))
     expect(a).toBe(b)
   })
+  // #1719: a subagent_handback envelope carries the JSONL agent id, and
+  // spoolId() keys on it — so a re-built envelope for the same finished
+  // sub-agent (different Date.now()-derived ts/messageId across a
+  // restart or the onFinish race) collapses to one spool entry instead
+  // of re-firing the handback turn.
+  it('subagent_handback → s:handback:<jsonl_agent_id>, stable across ts', () => {
+    const a = spoolId(
+      msg({
+        messageId: 1700_000_000_000,
+        ts: 1700_000_000_000,
+        meta: { source: 'subagent_handback', subagent_jsonl_id: 'abc-123' },
+      }),
+    )
+    const b = spoolId(
+      msg({
+        messageId: 1700_000_999_999,
+        ts: 1700_000_999_999,
+        meta: { source: 'subagent_handback', subagent_jsonl_id: 'abc-123' },
+      }),
+    )
+    expect(a).toBe('s:handback:abc-123')
+    expect(b).toBe(a) // stable across Date.now() drift / restart re-build
+  })
+  it('subagent_handback for distinct sub-agents stays distinct', () => {
+    const a = spoolId(
+      msg({ messageId: 0, meta: { source: 'subagent_handback', subagent_jsonl_id: 'a' } }),
+    )
+    const b = spoolId(
+      msg({ messageId: 0, meta: { source: 'subagent_handback', subagent_jsonl_id: 'b' } }),
+    )
+    expect(a).not.toBe(b)
+  })
+  it('subagent_handback without jsonl id falls back to legacy id (back-compat)', () => {
+    const a = spoolId(
+      msg({ messageId: 555, meta: { source: 'subagent_handback' }, ts: 100 }),
+    )
+    // messageId > 0 → legacy m:<chat>:<msgId> still wins.
+    expect(a).toBe('m:c1:555')
+  })
+})
+
+describe('inbound-spool — subagent_handback dedup across restart re-build (#1719)', () => {
+  it('two handback envelopes for the same jsonl id collapse to one live entry', () => {
+    const fs = fakeFs()
+    const s = createInboundSpool({ path: PATH, fs })
+    const first = msg({
+      messageId: 1700_000_000_000,
+      ts: 1700_000_000_000,
+      meta: { source: 'subagent_handback', subagent_jsonl_id: 'jsonl-xyz' },
+    })
+    // Simulates a second onFinish (or boot-replay re-build) for the
+    // same sub-agent. Different ts / messageId — same jsonl id.
+    const second = msg({
+      messageId: 1700_000_999_999,
+      ts: 1700_000_999_999,
+      meta: { source: 'subagent_handback', subagent_jsonl_id: 'jsonl-xyz' },
+    })
+    expect(s.put('worker', first)).toBe(true)
+    expect(s.put('worker', second)).toBe(false) // deduped, no re-fire
+    expect(s.liveCount()).toBe(1)
+    expect(s.liveEntries()).toHaveLength(1)
+  })
 })
 
 describe('inbound-spool — put / ack / dedup', () => {

package/telegram-plugin/tests/multi-turn-continuity.test.ts

@@ -37,7 +37,6 @@ function makeDeps(bot: FakeBot, overrides?: Partial<StreamReplyDeps>): StreamRep
     disableLinkPreview: true,
     defaultFormat: 'html',
     logStreamingEvent: () => {},
-    endStatusReaction: () => {},
     historyEnabled: false,
     recordOutbound: () => {},
     writeError: () => {},

package/telegram-plugin/tests/outbound-ordering.test.ts

@@ -215,7 +215,6 @@ describe('wrapBot + handleStreamReply + reply ordering', () => {
       disableLinkPreview: true,
       defaultFormat: 'text',
       logStreamingEvent: () => {},
-      endStatusReaction: () => {},
       historyEnabled: false,
       recordOutbound: () => {},
       writeError: () => {},

package/telegram-plugin/tests/parse-mode-rotation.test.ts

@@ -37,7 +37,6 @@ function makeDeps(bot: FakeBot, overrides?: Partial<StreamReplyDeps>): StreamRep
     disableLinkPreview: true,
     defaultFormat: 'html',
     logStreamingEvent: () => {},
-    endStatusReaction: () => {},
     historyEnabled: false,
     recordOutbound: () => {},
     writeError: () => {},