switchroom 0.19.19 → 0.19.23

package/telegram-plugin/gateway/status-pin-api.ts

@@ -0,0 +1,145 @@
+/**
+ * status-pin-api.ts — the Bot API surface the status-pin driver calls, bound to
+ * the gateway's retry policy + send gate (#3664).
+ *
+ * Extracted out of `gateway.ts` (which is under a line ratchet,
+ * `scripts/check-gateway-line-ratchet.mjs`) so the two invariants below can be
+ * enforced in code and proven in isolation, instead of resting on defaults that
+ * live in other modules.
+ *
+ * INVARIANT 1 — the bot must exist (`assertBotReady`).
+ * `lockedBot` in gateway.ts is declared `let lockedBot!: Bot<Context>`. The
+ * definite-assignment `!` is an ASSERTION, not a guarantee: it told `tsc` to
+ * stop checking, which is exactly why the boot orphan sweep dereferencing an
+ * unset `lockedBot` at module-eval time compiled clean and shipped. Every unpin
+ * it issued failed with the opaque
+ * `undefined is not an object (evaluating 'lockedBot.api')`, which read like a
+ * Telegram fault for a month. The ordering FIX is the two-condition gate in
+ * `boot-sweep-gate.ts`; this is the BACKSTOP, so any future pre-ready caller
+ * gets a named, greppable `STATUS_PIN_BOT_NOT_READY` instead.
+ *
+ * INVARIANT 2 — a shed send must not look like a landed one (`assertLanded`).
+ * See the docblock on `assertLanded`.
+ */
+
+import type { PinBotApi } from '../status-pin-driver.js'
+import { SEND_GATE_SHED } from '../send-gate.js'
+
+/** Thrown when the pin API is used before `lockedBot` has been assigned. */
+export class BotNotReadyError extends Error {
+  constructor(what: string) {
+    super(
+      `STATUS_PIN_BOT_NOT_READY: ${what} used before initGatewayBot() assigned ` +
+        `lockedBot — the boot sweep must run behind the boot-sweep gate`,
+    )
+    this.name = 'BotNotReadyError'
+  }
+}
+
+/** Narrow `bot` to non-null or throw {@link BotNotReadyError}. */
+export function assertBotReady<T>(bot: T | undefined | null, what: string): T {
+  if (bot == null) throw new BotNotReadyError(what)
+  return bot
+}
+
+/** Thrown when the outbound send gate SHED a pin/unpin — it never reached Telegram. */
+export class SendGateShedError extends Error {
+  constructor(verb: string) {
+    super(`STATUS_PIN_SEND_SHED: ${verb} was shed by the send gate and never reached Telegram`)
+    this.name = 'SendGateShedError'
+  }
+}
+
+/**
+ * Convert a send-gate SHED into a throw.
+ *
+ * The pin state machine reads "the call did not throw" as "the pin/unpin
+ * LANDED": `reconcilePin` claims the message on a resolved pin, and treats a
+ * resolved unpin as confirmed — dropping the in-memory claim AND (via the null
+ * branch of `reconcileAndPersistStatusPin`) the durable `status-pins.json` row.
+ * A send that was DROPPED but resolved success-shaped therefore reopens #3664
+ * Defect B through a second door: the still-pinned message loses its last
+ * record and no reaper or boot sweep can ever find it again.
+ *
+ * `robustApiCall` does not throw on a shed — it RESOLVES the gate's
+ * `SEND_GATE_SHED` sentinel (send-gate.ts). Today a status-pin call
+ * cannot be shed, because it is an untagged SEND and untagged sends admit as
+ * `UNTAGGED_SEND_CLASS`, which is `'critical'` and is never shed.
+ * But that is a DEFAULT IN ANOTHER MODULE: tagging `status-pin.unpin` with a
+ * `priorityClass`, or changing that default, would silently reopen the defect
+ * with no test failing. This turns the default into an enforced invariant.
+ *
+ * Sentinel ONLY. A plain `undefined` is deliberately NOT a failure: the gate
+ * also resolves `undefined` for a benign no-op drop (identical payload already
+ * on screen) and the retry policy resolves `undefined` for swallowed benign
+ * 400s. Conflating those with a shed is the exact ambiguity `SEND_GATE_SHED`
+ * was introduced to remove (see its docblock in send-gate.ts).
+ *
+ * Known residual: a `useful`-classed send whose queue TTL EXPIRES also resolves
+ * `undefined` (`send-gate.ts`, `outcome.result === 'expired'`) and so is not
+ * caught here. That is unreachable for status pins — they are untagged, hence
+ * `critical`, which is never TTL-dropped — and closing it would mean treating
+ * every benign `undefined` as a failure, which is strictly worse. If a status
+ * pin is ever deliberately tagged `useful`, this needs a distinguishable
+ * expiry sentinel too.
+ */
+export function assertLanded(result: unknown, verb: string): unknown {
+  if (result === SEND_GATE_SHED) throw new SendGateShedError(verb)
+  return result
+}
+
+/** Minimal shape of the wrapped gateway bot this module needs. */
+export interface PinCapableBot {
+  api: {
+    pinChatMessage: (
+      chatId: string | number,
+      messageId: number,
+      opts?: Record<string, unknown>,
+    ) => Promise<unknown>
+    unpinChatMessage: (chatId: string | number, messageId: number) => Promise<unknown>
+  }
+}
+
+/**
+ * The gateway's `robustApiCall` seam (retry policy + send gate), erased to the
+ * shape this module needs so `gateway.ts` can pass it with a single cast.
+ */
+export type RobustApiSeam = (
+  fn: () => Promise<unknown>,
+  opts: Record<string, unknown>,
+) => Promise<unknown>
+
+/**
+ * Build the pin API.
+ *
+ * `getBot` is read LAZILY on every call — `lockedBot` is assigned late, inside
+ * `initGatewayBot()` — and asserted non-null (INVARIANT 1). `robust` is the
+ * gateway's `robustApiCall`, so pins/unpins ride the send gate and retry policy
+ * exactly as before this extraction, with the shed sentinel converted to a
+ * throw on the way out (INVARIANT 2).
+ */
+export function createStatusPinApi(
+  getBot: () => PinCapableBot | undefined,
+  robust: RobustApiSeam,
+): PinBotApi {
+  const call = (verb: string, fn: (bot: PinCapableBot) => Promise<unknown>, chatId: string) =>
+    robust(() => fn(assertBotReady(getBot(), verb)), { chat_id: chatId, verb }).then((r) =>
+      assertLanded(r, verb),
+    )
+  return {
+    pinChatMessage: (chat_id, message_id, opts) =>
+      call(
+        'status-pin.pin',
+        // allow-raw-bot-api: `call` runs this inside the injected `robust` seam (robustApiCall).
+        (bot) => bot.api.pinChatMessage(chat_id, message_id, opts),
+        String(chat_id),
+      ),
+    unpinChatMessage: (chat_id, message_id) =>
+      call(
+        'status-pin.unpin',
+        // allow-raw-bot-api: as above — wrapped by the injected `robust` seam.
+        (bot) => bot.api.unpinChatMessage(chat_id, message_id),
+        String(chat_id),
+      ),
+  }
+}

package/telegram-plugin/gateway/stream-render.ts

@@ -1856,6 +1856,12 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
             sentIds = delivery.sentIds
             chunkCount = delivery.chunkCount
             delivered = delivery.delivered
+            // #3702 — how many landed ids the read-back never corroborated.
+            // Stamped on the turn so `emitTurnRecord` writes `landed_unconfirmed`
+            // (omitted when 0): the fleet-visible counter for deliveries we call
+            // `complete` on the Bot API's ack alone, because the probe is
+            // inconclusive. Observational only — it never changes the status.
+            turn.landedUnconfirmed = delivery.landedUnconfirmed
 
             // #546 dedup: record what turn-flush just sent so a late-arriving
             // reply / stream_reply with the same content gets suppressed.

package/telegram-plugin/gateway/turn-record-status.ts

@@ -148,6 +148,20 @@ export interface TurnRecordRow {
   tools: number
   status: TurnStatus
   turn_id: string
+  /**
+   * How many landed message ids of this turn's backstop delivery the read-back
+   * probe never corroborated (`sentIds` minus the confirmed subset). OMITTED
+   * when zero, so an ordinary row is byte-identical to before.
+   *
+   * This is the measurable counterpart of the delivery verdict: since an
+   * inconclusive probe counts as delivered, a `complete` row carrying
+   * `landed_unconfirmed > 0` is a turn we called delivered on the Bot API's
+   * ack alone. Counting those is how the fleet can tell whether that optimism
+   * is ever wrong (a `landed_unconfirmed` turn followed by a "you never
+   * answered me" is the falsifying observation). It is NOT a failure signal and
+   * nothing escalates on it.
+   */
+  landed_unconfirmed?: number
 }
 
 /**
@@ -165,6 +179,7 @@ export function buildTurnRecord(
     turnId: string
     finalAnswerDelivered: boolean
     deliveryOutcome?: DeliveryOutcome
+    landedUnconfirmed?: number
   },
   endedAt: number,
 ): TurnRecordRow {
@@ -175,5 +190,9 @@ export function buildTurnRecord(
     tools: turn.toolCallCount ?? 0,
     status: computeTurnStatus(turn),
     turn_id: turn.turnId,
+    // Emitted ONLY when non-zero (see `TurnRecordRow.landed_unconfirmed`).
+    ...(turn.landedUnconfirmed != null && turn.landedUnconfirmed > 0
+      ? { landed_unconfirmed: turn.landedUnconfirmed }
+      : {}),
   }
 }

package/telegram-plugin/gateway/turns-jsonl-rotate.ts

@@ -13,6 +13,71 @@
  */
 export const TURNS_JSONL_MAX_BYTES = 5 * 1024 * 1024 // 5 MiB
 
+/** The agent state dir inside a switchroom agent container (bind-mounted to
+ *  `~/.switchroom/agents/<name>/` on the host). */
+export const DEFAULT_AGENT_STATE_DIR = '/state/agent'
+
+/**
+ * Resolve the agent state dir from the environment — the ONE reader for
+ * `SWITCHROOM_AGENT_STATE_DIR` that every writer into that dir must use.
+ *
+ * Normalisation is the point. The gateway had two writers into this dir a few
+ * lines apart (the context-occupancy snapshot and the turn record) reading the
+ * env var with two different expressions: a bare
+ * `process.env.SWITCHROOM_AGENT_STATE_DIR ?? '/state/agent'` and this one. For
+ * a value like `"/x/ "` or `"/x/"` those resolve to DIFFERENT directories, so
+ * the two artifacts of the same turn would land in two places — exactly the
+ * kind of split-brain state that made the turn-record leak hard to see. Both
+ * call sites now share this function.
+ *
+ * Blank/whitespace-only is treated as unset (a compose file that renders an
+ * empty value must not send state to `/turns.jsonl` at the filesystem root),
+ * and a trailing slash is stripped so joins never double it.
+ */
+export function resolveAgentStateDir(
+  env: Record<string, string | undefined> = process.env,
+): string {
+  const dir = env.SWITCHROOM_AGENT_STATE_DIR?.trim()
+  return dir != null && dir !== '' ? dir.replace(/\/+$/, '') : DEFAULT_AGENT_STATE_DIR
+}
+
+/**
+ * Resolve the turn-record path from the environment.
+ *
+ * `emitTurnRecord` used to hard-code `/state/agent/turns.jsonl`, ignoring
+ * `SWITCHROOM_AGENT_STATE_DIR` — which the sibling context-occupancy writer a
+ * few lines above it in `gateway.ts` already honours. Inside an agent container
+ * that path is the bind-mounted PRODUCTION `~/.switchroom/agents/<name>/
+ * turns.jsonl`, so any test that drove the real turn-end funnel while running
+ * in an agent container appended its synthetic rows straight into that agent's
+ * production turn record — even when the test had pointed every state-dir env
+ * var at a tmpdir. Those rows are then read back by the fleet-health L0 sensor
+ * (`src/fleet-health/scan.ts`) as that agent's real production turns.
+ *
+ * Honouring the env var is the root-cause fix: production containers do not set
+ * it (default unchanged), and a test that isolates its state dir now isolates
+ * its turn records with it.
+ *
+ * ── Operator coupling: setting this var RELOCATES the fleet-health input ──
+ *
+ * `agent.env` in `switchroom.yaml` is propagated verbatim into the container
+ * (`src/agents/compose.ts` `userEnv`), so an operator CAN set
+ * `SWITCHROOM_AGENT_STATE_DIR` on an agent. If they point it anywhere other
+ * than the bind-mounted `/state/agent`, this file moves with it — but the
+ * fleet-health L0 sensor reads `~/.switchroom/agents/<name>/turns.jsonl` at a
+ * FIXED host path (`src/fleet-health/scan.ts`). That agent then presents no
+ * turns artifact, lands in the scan's `skipped[]`, and goes quiet on the health
+ * board: no findings, no ledger entries, indistinguishable from a healthy
+ * agent. Do not set this var in production `agent.env`; it exists so tests (and
+ * the vitest `agent-state-dir-guard` setup file) can isolate agent state into a
+ * tmpdir.
+ */
+export function resolveTurnsJsonlPath(
+  env: Record<string, string | undefined> = process.env,
+): string {
+  return `${resolveAgentStateDir(env)}/turns.jsonl`
+}
+
 export interface RotateFs {
   statSize: (path: string) => number | undefined // undefined ⇒ file absent
   rename: (from: string, to: string) => void