switchroom 0.20.21 → 0.21.0

package/telegram-plugin/gateway/turn-active-marker.ts

@@ -38,15 +38,14 @@
 import {
   closeSync,
   existsSync,
-  mkdirSync,
   openSync,
   readFileSync,
   statSync,
   unlinkSync,
   utimesSync,
-  writeFileSync,
 } from "node:fs";
 import { join } from "node:path";
+import { mkdirStateSync, writeStateFileSync } from "../../src/util/state-owner.js";
 
 export const TURN_ACTIVE_MARKER_FILE = "turn-active.json";
 
@@ -82,8 +81,8 @@ export interface TurnActiveMarker {
  */
 export function writeTurnActiveMarker(stateDir: string, marker: TurnActiveMarker): void {
   try {
-    mkdirSync(stateDir, { recursive: true });
-    writeFileSync(
+    mkdirStateSync(stateDir, { recursive: true });
+    writeStateFileSync(
       join(stateDir, TURN_ACTIVE_MARKER_FILE),
       JSON.stringify(marker, null, 2) + "\n",
       { mode: 0o600 },

package/telegram-plugin/history.ts

@@ -25,8 +25,9 @@
  * chat exists in the DB.
  */
 
-import { chmodSync, existsSync, mkdirSync } from 'fs'
+import { chmodSync, existsSync } from 'fs'
 import { join } from 'path'
+import { adoptSqliteOwnership, mkdirStateSync } from '../src/util/state-owner.js'
 import { redact } from './secret-detect/redact.js'
 
 /**
@@ -81,7 +82,22 @@ function loadDatabaseClass(): SqliteDatabaseConstructor {
   }
 }
 
-export type MessageRole = 'user' | 'assistant'
+/**
+ * `system` is the CARD lane (#4571): a bot→user message the gateway posted as
+ * a UI surface rather than as an answer — the mid-turn activity card, the
+ * status pin, approval / boot / issues / worker-feed cards, restart notices,
+ * `progress_update` lines. Those consume real Telegram message ids, so the
+ * operator can (and does) quote-reply to one; before this lane existed the
+ * row simply did not exist and the reply resolved to nothing.
+ *
+ * They are deliberately NOT `assistant`: every delivery-accounting predicate
+ * in this file keys on `role = 'assistant'` meaning "the user was actually
+ * answered" (`getRecentOutboundCount`, `hasOutboundDeliveredSince`,
+ * `hasOutboundWithText`), and calling a card an answer would silently suppress
+ * the silence/over-ping/represent safety nets. A distinct value keeps every
+ * existing predicate byte-identical while making the id resolvable.
+ */
+export type MessageRole = 'user' | 'assistant' | 'system'
 
 export interface RecordedMessage {
   chat_id: string
@@ -127,6 +143,14 @@ export interface RecordedMessage {
   forwarded_from_id: string | null
   forwarded_date: string | null
   forwarded_message_id: number | null
+  /**
+   * Discriminator for a `system` (card) row: the send's `verb` tag as it was
+   * passed to the gateway's retry wrapper, normalised (`activity-summary.send`
+   * → `activity-summary`). Null for `user` / `assistant` rows and for an
+   * untagged send. Surfaced to the agent as `reply_to_kind` when a native
+   * reply points at one of these messages.
+   */
+  kind: string | null
 }
 
 export interface QueryOptions {
@@ -134,6 +158,14 @@ export interface QueryOptions {
   thread_id?: number | null
   limit?: number
   before_message_id?: number
+  /**
+   * Include `system` (card) rows in the result. DEFAULT FALSE, deliberately:
+   * cards are ephemeral UI, and `get_recent_messages` renders straight into
+   * the operator-visible model context — a wall of activity-card rows there
+   * would be a regression. Card rows stay RESOLVABLE by id (see
+   * {@link lookupMessageRoleAndText}) without being LISTED.
+   */
+  include_system?: boolean
 }
 
 const DEFAULT_LIMIT = 10
@@ -185,7 +217,7 @@ function isValidMessageId(id: unknown): id is number {
 export function initHistory(stateDir: string, retentionDays = 30): void {
   if (db != null) return
   const Database = loadDatabaseClass()
-  mkdirSync(stateDir, { recursive: true, mode: 0o700 })
+  mkdirStateSync(stateDir, { recursive: true, mode: 0o700 })
   const path = join(stateDir, 'history.db')
   dbPath = path
   db = new Database(path, { create: true })
@@ -212,6 +244,7 @@ export function initHistory(stateDir: string, retentionDays = 30): void {
       group_id       INTEGER,
       reply_to_message_id INTEGER,
       reply_to_text  TEXT,
+      kind           TEXT,
       PRIMARY KEY (chat_id, thread_id, message_id)
     )
   `)
@@ -232,6 +265,10 @@ export function initHistory(stateDir: string, retentionDays = 30): void {
     "forwarded_from_id TEXT",
     "forwarded_date TEXT",
     "forwarded_message_id INTEGER",
+    // #4571 — card/system-surface discriminator. Nullable with no default, so
+    // the ALTER is instant on a multi-thousand-row live DB and every existing
+    // row keeps its exact contents (SQLite backfills NULL without a rewrite).
+    "kind TEXT",
   ]) {
     try {
       db.exec(`ALTER TABLE messages ADD COLUMN ${column}`)
@@ -300,6 +337,12 @@ export function initHistory(stateDir: string, retentionDays = 30): void {
     const f = path + suffix
     if (existsSync(f)) { try { chmodSync(f, 0o644) } catch { /* ignore */ } }
   }
+  // Ownership rides the same hook as the mode, for the same reason. SQLite
+  // creates `-wal`/`-shm` itself, in C, so no `node:fs` write helper can ever
+  // see them — this is the only place we get to fix their owner. A root
+  // gateway would otherwise leave root:root DB files in an agent-owned state
+  // dir and EACCES every non-root reader. No-op off the root path.
+  adoptSqliteOwnership(path)
 
   if (retentionDays > 0) {
     const cutoff = Math.floor(Date.now() / 1000) - retentionDays * 86400
@@ -422,6 +465,9 @@ export function checkpointWal(): boolean {
         const f = dbPath + suffix
         if (existsSync(f)) { try { chmodSync(f, 0o644) } catch { /* ignore */ } }
       }
+      // …and ownership with it: a TRUNCATE checkpoint DELETES and RE-CREATES
+      // the sidecars, so the owner we set at init is gone by here.
+      adoptSqliteOwnership(dbPath)
     }
     return true
   } catch {
@@ -609,12 +655,29 @@ export function recordOutbound(args: RecordOutboundArgs): void {
       (chat_id, thread_id, message_id, role, user, user_id, ts, text, attachment_kind, group_id)
     VALUES (?, ?, ?, 'assistant', NULL, NULL, ?, ?, ?, ?)
   `)
+  // #4571 — a real reply ALWAYS wins over a provisional card row.
+  //
+  // The system-lane observer (gateway `robustApiCall`) records every sent
+  // message the moment the API resolves, which is BEFORE the caller reaches
+  // its own `recordOutbound`. `INSERT OR REPLACE` alone would not reliably
+  // overwrite that row: the unique key folds `thread_id`, and the observer
+  // derives the thread from the Telegram response (which sets
+  // `message_thread_id` on reply chains in plain supergroups) while this
+  // writer uses the gateway's own `threadId` — a mismatch would leave BOTH
+  // rows and let the card row shadow the answer for id lookups. Deleting on
+  // (chat_id, message_id) — unique within a chat regardless of thread, the
+  // same assumption `recordEdit` / `recordReaction` already make — makes the
+  // promotion exact and is a no-op when no observer row exists.
+  const dropSystem = requireDb().prepare(
+    `DELETE FROM messages WHERE chat_id = ? AND message_id = ? AND role = 'system'`,
+  )
   // bun:sqlite has a transaction() helper. Cheap insurance against partial
   // writes if the process dies mid-loop. The transaction signature is
   // typed as variadic-unknown for genericity; cast the typed callback
   // through the wider shape.
   const tx = requireDb().transaction(((rows: Array<{ id: number; text: string; attachKind: string | null }>) => {
     for (const r of rows) {
+      dropSystem.run(args.chat_id, r.id)
       stmt.run(args.chat_id, args.thread_id ?? null, r.id, ts, r.text, r.attachKind, groupId)
     }
   }) as (...args: unknown[]) => unknown)
@@ -634,6 +697,97 @@ export function recordOutbound(args: RecordOutboundArgs): void {
   }
 }
 
+export interface RecordSystemOutboundArgs {
+  chat_id: string
+  thread_id: number | null | undefined
+  message_id: number
+  /** Normalised send verb (`activity-summary`, `approval-card`, …) or null. */
+  kind: string | null | undefined
+  /** Rendered text as Telegram echoed it back. May be empty. */
+  text: string
+  /** Unix SECONDS. Defaults to now. */
+  ts?: number
+}
+
+/**
+ * Record a CARD / system-surface outbound (#4571).
+ *
+ * Conditional insert on (chat_id, message_id): if ANY row already exists for
+ * that id — a real `assistant` reply recorded by `recordOutbound`, an inbound,
+ * or a previously-recorded card — this is a no-op and returns false. That is
+ * what makes the call safe to fire from a blanket send observer that cannot
+ * distinguish a fresh send from an edit of a message it already knows: an edit
+ * returns the SAME `message_id`, hits the `NOT EXISTS` guard, and falls through
+ * to {@link updateSystemOutboundText} instead of duplicating a row per edit.
+ *
+ * Never throws — a card row is a nice-to-have, and a failure here must not
+ * break the send path it is observing. Failures are logged via `warnHistory`.
+ *
+ * Returns true iff a new row was inserted.
+ */
+export function recordSystemOutbound(args: RecordSystemOutboundArgs): boolean {
+  if (!isValidMessageId(args.message_id)) return false
+  // History disabled / not yet initialised: stay silent. This is called from a
+  // blanket send observer, so a warn here would be one stderr line per API call.
+  if (db == null) return false
+  try {
+    const res = requireDb()
+      .prepare(`
+        INSERT INTO messages
+          (chat_id, thread_id, message_id, role, user, user_id, ts, text, attachment_kind, group_id, kind)
+        SELECT ?, ?, ?, 'system', NULL, NULL, ?, ?, NULL, NULL, ?
+         WHERE NOT EXISTS (
+           SELECT 1 FROM messages WHERE chat_id = ? AND message_id = ?
+         )
+      `)
+      .run(
+        args.chat_id,
+        args.thread_id ?? null,
+        args.message_id,
+        args.ts ?? Math.floor(Date.now() / 1000),
+        // Same outbound redaction chokepoint as recordOutbound: a card body is
+        // rendered from live tool activity and can quote a secret.
+        redact(args.text),
+        args.kind ?? null,
+        args.chat_id,
+        args.message_id,
+      ) as { changes?: number }
+    return (res?.changes ?? 0) > 0
+  } catch (err) {
+    warnHistory(
+      `recordSystemOutbound: INSERT failed (chat=${args.chat_id} id=${args.message_id}): ` +
+        `${err instanceof Error ? err.message : String(err)} — a posted card will not be ` +
+        `resolvable if the operator quote-replies to it`,
+    )
+    return false
+  }
+}
+
+/**
+ * Refresh a card row's stored text in place (#4571). Only ever touches a
+ * `system` row, so an edit of a real reply can never be rewritten through this
+ * path (`recordEdit` owns that).
+ *
+ * `ts` is deliberately NOT bumped: it is the card's POST time, which is what
+ * retention prunes on. Never throws. Returns true iff a row was updated.
+ */
+export function updateSystemOutboundText(args: {
+  chat_id: string
+  message_id: number
+  text: string
+}): boolean {
+  try {
+    const res = requireDb()
+      .prepare(
+        `UPDATE messages SET text = ? WHERE chat_id = ? AND message_id = ? AND role = 'system'`,
+      )
+      .run(redact(args.text), args.chat_id, args.message_id) as { changes?: number }
+    return (res?.changes ?? 0) > 0
+  } catch {
+    return false
+  }
+}
+
 interface RecordEditArgs {
   chat_id: string
   message_id: number
@@ -781,16 +935,27 @@ export function getLatestInboundMessageId(
 export function lookupMessageRoleAndText(
   chatId: string,
   messageId: number,
-): { role: 'user' | 'assistant'; text: string } | null {
-  const row = requireDb()
-    .prepare(
-      `SELECT role, text FROM messages WHERE chat_id = ? AND message_id = ? LIMIT 1`,
-    )
-    .get(chatId, messageId) as
-    | { role: 'user' | 'assistant'; text: string | null }
+  opts?: {
+    /**
+     * Also resolve `system` (card) rows. DEFAULT FALSE so the two
+     * authorship-sensitive callers — the reaction trigger's
+     * `role === 'assistant'` bot-authored predicate and the
+     * `reaction_dispatch` preview — keep their exact pre-#4571 behaviour
+     * (a card was invisible to them, and still is). The reply-antecedent
+     * resolver opts IN: that is the whole point of the card lane.
+     */
+    includeSystem?: boolean
+  },
+): { role: MessageRole; text: string; kind: string | null } | null {
+  const sql =
+    `SELECT role, text, kind FROM messages WHERE chat_id = ? AND message_id = ?` +
+    (opts?.includeSystem === true ? '' : ` AND role <> 'system'`) +
+    ` LIMIT 1`
+  const row = requireDb().prepare(sql).get(chatId, messageId) as
+    | { role: MessageRole; text: string | null; kind: string | null }
     | undefined
   if (!row) return null
-  return { role: row.role, text: row.text ?? '' }
+  return { role: row.role, text: row.text ?? '', kind: row.kind ?? null }
 }
 
 export function getRecentOutboundCount(
@@ -1007,6 +1172,8 @@ export function query(opts: QueryOptions): RecordedMessage[] {
   const limit = Math.min(MAX_LIMIT, Math.max(1, opts.limit ?? DEFAULT_LIMIT))
   const params: unknown[] = [opts.chat_id]
   let sql = 'SELECT * FROM messages WHERE chat_id = ?'
+  // #4571 — card rows are resolvable, not listable. See QueryOptions.include_system.
+  if (opts.include_system !== true) sql += " AND role <> 'system'"
   if (opts.thread_id !== undefined) {
     if (opts.thread_id === null) {
       sql += ' AND thread_id IS NULL'

package/telegram-plugin/registry/turns-schema.ts

@@ -36,8 +36,9 @@
  *   otherwise; the gateway then resumes or reports accordingly.
  */
 
-import { chmodSync, mkdirSync } from 'fs'
+import { chmodSync } from 'fs'
 import { join } from 'path'
+import { adoptSqliteOwnership, mkdirStateSync } from '../../src/util/state-owner.js'
 
 // ---------------------------------------------------------------------------
 // bun:sqlite lazy-loader (same pattern as history.ts)
@@ -302,7 +303,7 @@ function applySchema(db: SqliteDatabase): void {
 export function openTurnsDb(agentDir: string): SqliteDatabase {
   const Database = loadDatabaseClass()
   const dir = join(agentDir, 'telegram')
-  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  mkdirStateSync(dir, { recursive: true, mode: 0o700 })
   const path = join(dir, 'registry.db')
   const db = new Database(path, { create: true })
   applySchema(db)
@@ -318,6 +319,11 @@ export function openTurnsDb(agentDir: string): SqliteDatabase {
   } catch {
     /* ignore — chmod not supported on some FUSE mounts */
   }
+  // Same reasoning as the chmod above, for the owner rather than the mode:
+  // a root-running gateway must not leave root:root DB files in an
+  // agent-owned state dir. `-wal`/`-shm` are created by SQLite in C, so this
+  // hook is the only place we can reach them. No-op off the root path.
+  adoptSqliteOwnership(path)
   return db
 }
 

package/telegram-plugin/tests/buzz-mirror.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { describe, it, expect, beforeEach, afterEach, afterAll, vi } from 'vitest'
 import { mkdtempSync, rmSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
@@ -29,6 +29,17 @@ function mirrorWith(sender: (m: OutboundToBuzzMessage) => boolean, opts?: { defa
 
 const BUZZ_COORDS = { channelId: 'chan-A', eventId: 'evt-1', threadRoot: 'root-1' }
 
+// Cross-FILE isolation. `getBuzzMirror()` is a module-level singleton and the
+// last describe here boots one (`maybeBootBuzzMirror`) with no trailing reset —
+// every `beforeEach` in this file resets on the way IN, nothing resets on the
+// way OUT. `bun test` runs every file in ONE process with no guaranteed file
+// order, so a booted mirror leaks into whichever suite runs next: sendReply's
+// Buzz hook (outbound-send-path.ts:2658) then fires in suites that never wired
+// its deps and dies on `findLatestTurnForChat is not a function` (observed:
+// 43 failures in send-reply-golden.test.ts, purely from readdir order).
+// Unconditional teardown here is the only ordering-proof fix.
+afterAll(() => __resetBuzzMirrorForTests())
+
 describe('BuzzMirror.mirrorReplyDelivered — routing + S1 owner guard', () => {
   beforeEach(() => __resetBuzzMirrorForTests())