switchroom 0.19.48 → 0.20.1

package/telegram-plugin/dist/server.js

@@ -17188,12 +17188,12 @@ function classifyClaudeError(raw) {
   try {
     return classifyInner(raw);
   } catch {
-    return "unknown-4xx";
+    return "unknown-5xx";
   }
 }
 function classifyInner(raw) {
   if (raw == null)
-    return "unknown-4xx";
+    return "unknown-5xx";
   const obj = typeof raw === "object" ? raw : {};
   const errorType = extractString(obj, "error_type") ?? extractString(obj, "type") ?? extractString(getNestedObj(obj, "error"), "type") ?? "";
   const errorCode = extractString(obj, "code") ?? extractString(getNestedObj(obj, "error"), "code") ?? "";
@@ -17238,13 +17238,16 @@ ${message}`;
   if (errorType === "agent-restarted-unexpectedly" || errorCode === "agent-restarted-unexpectedly") {
     return "agent-restarted-unexpectedly";
   }
+  if ((status == null || status >= 500) && (errorType === "server_error" || errorCode === "server_error" || sdkCode === "server_error" || errorType === "api_error" || errorCode === "api_error" || sdkCode === "api_error")) {
+    return "transport-transient";
+  }
   if (status != null) {
     if (status >= 400 && status < 500)
       return "unknown-4xx";
     if (status >= 500 && status < 600)
       return "unknown-5xx";
   }
-  return "unknown-4xx";
+  return "unknown-5xx";
 }
 function extractString(obj, key) {
   const v = obj[key];
@@ -17792,7 +17795,7 @@ ${errStr}`) ? "rate-limited" : "quota-exhausted" : classifyClaudeError({ type: e
   const raw = embeddedError ?? obj;
   const kind = classifyClaudeError(embeddedError ?? obj);
   const detail = extractDetailMessage(embeddedError) ?? extractDetailMessage(obj) ?? String(type ?? "");
-  const transient = kind === "rate-limited";
+  const transient = kind === "rate-limited" || kind === "transport-transient";
   const retry = extractRetryState(obj);
   const terminal = !transient ? true : retry.retryAttempt != null && retry.maxRetries != null ? retry.retryAttempt >= retry.maxRetries : isErrorLine;
   return { kind, raw, detail, transient, terminal };

package/telegram-plugin/gateway/access-store.test.ts

@@ -0,0 +1,234 @@
+/**
+ * Unit tests for access-store.ts — the access/allowlist file layer extracted
+ * from gateway.ts (switchroom#4248).
+ *
+ * These lock in the behavior that used to be inline in gateway.ts, in
+ * particular the init-time-only static-mode snapshot (BOOT_ACCESS): in static
+ * mode the allowlist is read ONCE when the store is built and frozen for the
+ * life of the store, so a later edit to access.json on disk is NOT observed.
+ * That timing is the whole reason the store is a factory rather than a set of
+ * lazy free functions — this suite is the outcome guard for it.
+ *
+ * Run with: npx vitest run telegram-plugin/gateway/access-store.test.ts
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, writeFileSync, readFileSync, existsSync, readdirSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { createAccessStore, type AccessStoreDeps } from './access-store.js'
+import type { Access } from './gateway.js'
+
+function makeDeps(dir: string, isStatic: boolean): AccessStoreDeps {
+  return {
+    accessFile: join(dir, 'access.json'),
+    peopleFile: join(dir, 'people.json'),
+    stateDir: dir,
+    isStatic,
+  }
+}
+
+describe('access-store', () => {
+  let dir: string
+  let stderrSpy: ReturnType<typeof vi.spyOn>
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'access-store-'))
+    stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true)
+  })
+
+  afterEach(() => {
+    stderrSpy.mockRestore()
+    rmSync(dir, { recursive: true, force: true })
+  })
+
+  // ─── defaultAccess ─────────────────────────────────────────────────────────
+
+  it('defaultAccess returns a pairing-mode empty allowlist', () => {
+    const store = createAccessStore(makeDeps(dir, false))
+    expect(store.defaultAccess()).toEqual({
+      dmPolicy: 'pairing',
+      allowFrom: [],
+      groups: {},
+      pending: {},
+    })
+  })
+
+  // ─── readAccessFile ────────────────────────────────────────────────────────
+
+  it('readAccessFile returns defaultAccess when the file is missing (ENOENT)', () => {
+    const store = createAccessStore(makeDeps(dir, false))
+    expect(store.readAccessFile()).toEqual(store.defaultAccess())
+  })
+
+  it('readAccessFile parses a valid access.json and projects known fields', () => {
+    writeFileSync(
+      join(dir, 'access.json'),
+      JSON.stringify({
+        dmPolicy: 'allowlist',
+        allowFrom: ['111'],
+        groups: { '-100': { requireMention: true, allowFrom: ['222'] } },
+        pending: {},
+        parseMode: 'text',
+        historyEnabled: false,
+      }),
+    )
+    const store = createAccessStore(makeDeps(dir, false))
+    const a = store.readAccessFile()
+    expect(a.dmPolicy).toBe('allowlist')
+    expect(a.allowFrom).toEqual(['111'])
+    expect(a.groups['-100']).toEqual({ requireMention: true, allowFrom: ['222'] })
+    expect(a.parseMode).toBe('text')
+    expect(a.historyEnabled).toBe(false)
+  })
+
+  it('readAccessFile fails closed on number-array fields (the hand-edit bug)', () => {
+    // Unquoted IDs parse as numbers; validateStringArray must drop them.
+    writeFileSync(
+      join(dir, 'access.json'),
+      JSON.stringify({ dmPolicy: 'allowlist', allowFrom: [12345], groups: {}, pending: {} }),
+    )
+    const store = createAccessStore(makeDeps(dir, false))
+    expect(store.readAccessFile().allowFrom).toEqual([])
+    expect(stderrSpy).toHaveBeenCalled()
+  })
+
+  it('readAccessFile moves a corrupt file aside and returns defaultAccess', () => {
+    writeFileSync(join(dir, 'access.json'), '{ not valid json')
+    const store = createAccessStore(makeDeps(dir, false))
+    expect(store.readAccessFile()).toEqual(store.defaultAccess())
+    // Original replaced by a .corrupt-* sibling.
+    expect(existsSync(join(dir, 'access.json'))).toBe(false)
+    const corrupt = readdirSync(dir).filter((f) => f.startsWith('access.json.corrupt-'))
+    expect(corrupt.length).toBe(1)
+  })
+
+  // ─── loadAccess — non-static re-reads live ─────────────────────────────────
+
+  it('loadAccess re-reads the file on every call in non-static mode', () => {
+    writeFileSync(
+      join(dir, 'access.json'),
+      JSON.stringify({ dmPolicy: 'allowlist', allowFrom: ['111'], groups: {}, pending: {} }),
+    )
+    const store = createAccessStore(makeDeps(dir, false))
+    expect(store.loadAccess().allowFrom).toEqual(['111'])
+    // Edit on disk is observed immediately (no snapshot in non-static mode).
+    writeFileSync(
+      join(dir, 'access.json'),
+      JSON.stringify({ dmPolicy: 'allowlist', allowFrom: ['222'], groups: {}, pending: {} }),
+    )
+    expect(store.loadAccess().allowFrom).toEqual(['222'])
+  })
+
+  // ─── Static-mode BOOT_ACCESS snapshot (init-time semantics) ────────────────
+
+  it('static mode snapshots at build time: downgrades pairing→allowlist and clears pending', () => {
+    writeFileSync(
+      join(dir, 'access.json'),
+      JSON.stringify({
+        dmPolicy: 'pairing',
+        allowFrom: ['111'],
+        groups: {},
+        pending: { code123: { senderId: 's', chatId: 'c', createdAt: 1, expiresAt: 2, replies: 0 } },
+      }),
+    )
+    const store = createAccessStore(makeDeps(dir, true))
+    const a = store.loadAccess()
+    expect(a.dmPolicy).toBe('allowlist')
+    expect(a.pending).toEqual({})
+    expect(a.allowFrom).toEqual(['111'])
+  })
+
+  it('static mode freezes the allowlist: an on-disk edit after build is NOT observed', () => {
+    writeFileSync(
+      join(dir, 'access.json'),
+      JSON.stringify({ dmPolicy: 'allowlist', allowFrom: ['111'], groups: {}, pending: {} }),
+    )
+    const store = createAccessStore(makeDeps(dir, true))
+    expect(store.loadAccess().allowFrom).toEqual(['111'])
+    // Change the file after the store was built.
+    writeFileSync(
+      join(dir, 'access.json'),
+      JSON.stringify({ dmPolicy: 'allowlist', allowFrom: ['999'], groups: {}, pending: {} }),
+    )
+    // Still the boot snapshot — this is the init-time-only guarantee.
+    expect(store.loadAccess().allowFrom).toEqual(['111'])
+  })
+
+  // ─── saveAccess ────────────────────────────────────────────────────────────
+
+  it('saveAccess writes access.json atomically in non-static mode', () => {
+    const store = createAccessStore(makeDeps(dir, false))
+    const a: Access = { dmPolicy: 'allowlist', allowFrom: ['abc'], groups: {}, pending: {} }
+    store.saveAccess(a)
+    const written = JSON.parse(readFileSync(join(dir, 'access.json'), 'utf8'))
+    expect(written.allowFrom).toEqual(['abc'])
+    // No leftover temp file.
+    expect(existsSync(join(dir, 'access.json.tmp'))).toBe(false)
+  })
+
+  it('saveAccess is a no-op in static mode', () => {
+    const store = createAccessStore(makeDeps(dir, true))
+    store.saveAccess({ dmPolicy: 'allowlist', allowFrom: ['abc'], groups: {}, pending: {} })
+    expect(existsSync(join(dir, 'access.json'))).toBe(false)
+  })
+
+  // ─── pruneExpired ──────────────────────────────────────────────────────────
+
+  it('pruneExpired removes expired pending entries and reports whether it changed', () => {
+    const now = Date.now()
+    const store = createAccessStore(makeDeps(dir, false))
+    const a: Access = {
+      dmPolicy: 'pairing',
+      allowFrom: [],
+      groups: {},
+      pending: {
+        old: { senderId: 's', chatId: 'c', createdAt: 1, expiresAt: now - 1000, replies: 0 },
+        fresh: { senderId: 's', chatId: 'c', createdAt: 1, expiresAt: now + 100000, replies: 0 },
+      },
+    }
+    expect(store.pruneExpired(a)).toBe(true)
+    expect(Object.keys(a.pending)).toEqual(['fresh'])
+    // Second pass: nothing expired now → no change.
+    expect(store.pruneExpired(a)).toBe(false)
+  })
+
+  // ─── assertAllowedChat ─────────────────────────────────────────────────────
+
+  it('assertAllowedChat permits an allowFrom chat, a group chat, and rejects others', () => {
+    writeFileSync(
+      join(dir, 'access.json'),
+      JSON.stringify({
+        dmPolicy: 'allowlist',
+        allowFrom: ['111'],
+        groups: { '-100': { requireMention: false, allowFrom: [] } },
+        pending: {},
+      }),
+    )
+    const store = createAccessStore(makeDeps(dir, false))
+    expect(() => store.assertAllowedChat('111')).not.toThrow()
+    expect(() => store.assertAllowedChat(111)).not.toThrow() // number coerced
+    expect(() => store.assertAllowedChat('-100')).not.toThrow()
+    expect(() => store.assertAllowedChat('404')).toThrow(/not allowlisted/)
+  })
+
+  // ─── readPeopleFile ────────────────────────────────────────────────────────
+
+  it('readPeopleFile returns entries for a valid people.json', () => {
+    writeFileSync(
+      join(dir, 'people.json'),
+      JSON.stringify({ entries: [{ telegramUserId: '5', personId: 'p1' }] }),
+    )
+    const store = createAccessStore(makeDeps(dir, false))
+    expect(store.readPeopleFile()).toEqual([{ telegramUserId: '5', personId: 'p1' }])
+  })
+
+  it('readPeopleFile fails open to [] on missing or corrupt file', () => {
+    const store = createAccessStore(makeDeps(dir, false))
+    expect(store.readPeopleFile()).toEqual([]) // ENOENT
+    writeFileSync(join(dir, 'people.json'), 'not json')
+    expect(store.readPeopleFile()).toEqual([]) // corrupt
+    writeFileSync(join(dir, 'people.json'), JSON.stringify({ entries: 'nope' }))
+    expect(store.readPeopleFile()).toEqual([]) // entries not an array
+  })
+})

package/telegram-plugin/gateway/access-store.ts

@@ -0,0 +1,194 @@
+/**
+ * Access / allowlist file layer for the Telegram gateway.
+ *
+ * This module owns the read/write side of `access.json` (the per-agent DM
+ * allowlist + group policy + pairing state) and the read-only `people.json`
+ * projection. It was extracted verbatim out of `gateway.ts` (switchroom#4248)
+ * to relieve the gateway line-ratchet; the behavior is byte-identical to the
+ * inline version.
+ *
+ * Init-time semantics preserved: in static-access mode the gateway snapshots
+ * `access.json` ONCE at module-init time (the `BOOT_ACCESS` constant below),
+ * downgrades a `pairing` dmPolicy to `allowlist`, and clears pending pairings —
+ * so a static agent's allowlist is frozen for the life of the process. That
+ * snapshot must happen at the same point in startup as before, so the store is
+ * built by a factory (`createAccessStore`) that the gateway calls at the
+ * original `BOOT_ACCESS` site; the snapshot runs eagerly inside the factory,
+ * NOT lazily on first `loadAccess()`.
+ *
+ * The gateway-internal dependencies (`ACCESS_FILE`, `PEOPLE_FILE`, `STATE_DIR`
+ * path constants and the `STATIC` mode flag) are injected as explicit params so
+ * this module holds no runtime import of gateway.ts. The only back-reference is
+ * the `Access` / `GroupPolicy` types, imported type-only (erased under
+ * `isolatedModules`, so no runtime cycle) — the same seam
+ * `turn-start-surfaces.ts` already uses.
+ */
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { validateStringArray } from './access-validator.js'
+import type { RawPersonEntry } from './resolve-person.js'
+import type { Access } from './gateway.js'
+
+/** The per-group policy shape, derived from the exported `Access` type so the
+ *  store needs no extra symbol export from gateway.ts. */
+type GroupPolicy = Access['groups'][string]
+
+/** Gateway-internal deps the store needs, injected at build time. */
+export interface AccessStoreDeps {
+  /** Absolute path to `access.json` (gateway's `ACCESS_FILE`). */
+  accessFile: string
+  /** Absolute path to `people.json` (gateway's `PEOPLE_FILE`). */
+  peopleFile: string
+  /** State dir created (mode 0o700) before an atomic access.json write. */
+  stateDir: string
+  /** Static-access mode (`TELEGRAM_ACCESS_MODE === 'static'`). Freezes the
+   *  allowlist at init and turns `saveAccess` into a no-op. */
+  isStatic: boolean
+}
+
+/** The access/allowlist file layer, bound to one set of paths + mode. */
+export interface AccessStore {
+  defaultAccess(): Access
+  readAccessFile(): Access
+  loadAccess(): Access
+  readPeopleFile(): RawPersonEntry[]
+  assertAllowedChat(chat_id: string | number): void
+  saveAccess(a: Access): void
+  pruneExpired(a: Access): boolean
+}
+
+/**
+ * Build the access store. The `BOOT_ACCESS` snapshot happens eagerly here, so
+ * call this at the same point in gateway startup where `BOOT_ACCESS` used to be
+ * initialized — that keeps the static-mode freeze timing identical.
+ */
+export function createAccessStore(deps: AccessStoreDeps): AccessStore {
+  const { accessFile, peopleFile, stateDir, isStatic } = deps
+
+  function defaultAccess(): Access {
+    return { dmPolicy: 'pairing', allowFrom: [], groups: {}, pending: {} }
+  }
+
+  function readAccessFile(): Access {
+    try {
+      const raw = readFileSync(accessFile, 'utf8')
+      const parsed = JSON.parse(raw) as Partial<Access>
+      const allowFrom = validateStringArray('allowFrom', parsed.allowFrom ?? [])
+      const groups: Record<string, GroupPolicy> = {}
+      for (const [chatId, policy] of Object.entries(parsed.groups ?? {})) {
+        groups[chatId] = {
+          ...policy,
+          allowFrom: validateStringArray(`groups.${chatId}.allowFrom`, policy.allowFrom ?? []),
+        }
+      }
+      return {
+        dmPolicy: parsed.dmPolicy ?? 'pairing',
+        allowFrom,
+        groups,
+        pending: parsed.pending ?? {},
+        mentionPatterns: parsed.mentionPatterns,
+        ackReaction: parsed.ackReaction,
+        replyToMode: parsed.replyToMode,
+        textChunkLimit: parsed.textChunkLimit,
+        chunkMode: parsed.chunkMode,
+        parseMode: parsed.parseMode,
+        disableLinkPreview: parsed.disableLinkPreview,
+        coalescingGapMs: parsed.coalescingGapMs,
+        litellmNoticeWindowMs: parsed.litellmNoticeWindowMs,
+        coalesceMaxAttachments: parsed.coalesceMaxAttachments,
+        interruptSafeBoundary: parsed.interruptSafeBoundary,
+        interruptMaxWaitMs: parsed.interruptMaxWaitMs,
+        statusReactions: parsed.statusReactions,
+        historyEnabled: parsed.historyEnabled,
+        historyRetentionDays: parsed.historyRetentionDays,
+        // #596: telegram features projected into access.json by scaffold.
+        // Without these passthroughs, gateway readers (`access.voice_in`,
+        // `access.telegraph`, `access.stickers`) silently see undefined.
+        stickers: parsed.stickers,
+        voice_in: parsed.voice_in,
+        voice_out: parsed.voice_out,
+        telegraph: parsed.telegraph,
+        // #789: button-choice-confirmation config projected by scaffold.
+        button_choice_confirmation: parsed.button_choice_confirmation,
+      }
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') return defaultAccess()
+      try { renameSync(accessFile, `${accessFile}.corrupt-${Date.now()}`) } catch {}
+      process.stderr.write(`telegram gateway: access.json is corrupt, moved aside. Starting fresh.\n`)
+      return defaultAccess()
+    }
+  }
+
+  const BOOT_ACCESS: Access | null = isStatic
+    ? (() => {
+        const a = readAccessFile()
+        if (a.dmPolicy === 'pairing') {
+          process.stderr.write('telegram gateway: static mode — dmPolicy "pairing" downgraded to "allowlist"\n')
+          a.dmPolicy = 'allowlist'
+        }
+        a.pending = {}
+        return a
+      })()
+    : null
+
+  function loadAccess(): Access {
+    return BOOT_ACCESS ?? readAccessFile()
+  }
+
+  /**
+   * Read `people.json` (the scaffold's plain projection of `users:` entries
+   * that carry a `person_id`). Fail-open: ENOENT or corrupt/malformed JSON
+   * returns an empty array rather than throwing — this feature must never
+   * block startup. Unlike `access.json` this file is never gateway-mutated,
+   * so there's no "move corrupt file aside" concern; the scaffold owns and
+   * regenerates it on every reconcile.
+   */
+  function readPeopleFile(): RawPersonEntry[] {
+    try {
+      const raw = readFileSync(peopleFile, 'utf8')
+      const parsed = JSON.parse(raw) as { entries?: unknown }
+      if (!Array.isArray(parsed.entries)) return []
+      return parsed.entries as RawPersonEntry[]
+    } catch {
+      return []
+    }
+  }
+
+  function assertAllowedChat(chat_id: string | number): void {
+    const id = String(chat_id)
+    const access = loadAccess()
+    if (access.allowFrom.includes(id)) return
+    if (id in access.groups) return
+    throw new Error(`chat ${id} is not allowlisted — add via /telegram:access`)
+  }
+
+  function saveAccess(a: Access): void {
+    if (isStatic) return
+    mkdirSync(stateDir, { recursive: true, mode: 0o700 })
+    const tmp = accessFile + '.tmp'
+    writeFileSync(tmp, JSON.stringify(a, null, 2) + '\n', { mode: 0o600 })
+    renameSync(tmp, accessFile)
+  }
+
+  function pruneExpired(a: Access): boolean {
+    const now = Date.now()
+    let changed = false
+    for (const [code, p] of Object.entries(a.pending)) {
+      if (p.expiresAt < now) {
+        delete a.pending[code]
+        changed = true
+      }
+    }
+    return changed
+  }
+
+  return {
+    defaultAccess,
+    readAccessFile,
+    loadAccess,
+    readPeopleFile,
+    assertAllowedChat,
+    saveAccess,
+    pruneExpired,
+  }
+}