switchroom 0.14.61 → 0.14.63

package/telegram-plugin/gateway/auth-broker-client.ts

@@ -11,6 +11,7 @@
  */
 
 import { AuthBrokerClient as BrokerClient, type AddAccountCredentials } from '../../src/auth/broker/client.js'
+import type { ProviderName } from '../../src/auth/broker/protocol.js'
 import type { AuthBrokerClient } from './auth-command.js'
 
 /**
@@ -56,21 +57,30 @@ export async function getAuthBrokerClient(
 }
 
 /**
- * Add an account via the broker. Used exclusively by the `/auth add`
- * chat flow — the narrow {@link AuthBrokerClient} surface in
- * `auth-command.ts` deliberately omits `addAccount` because the verb
- * is gateway-routed (not handler-routed). Constructs and closes a
- * one-shot {@link BrokerClient} so the gateway doesn't need a
- * long-lived handle just for this verb.
+ * Add an account via the broker. Used by the `/auth add` chat flow
+ * (Anthropic) and the `/connect microsoft` device-code flow — the narrow
+ * {@link AuthBrokerClient} surface in `auth-command.ts` deliberately
+ * omits `addAccount` because the verb is gateway-routed (not
+ * handler-routed). Constructs and closes a one-shot {@link BrokerClient}
+ * so the gateway doesn't need a long-lived handle just for this verb.
+ *
+ * `provider` defaults to Anthropic (back-compat with the `/auth add`
+ * caller, which omits it). The device-code flow passes `"microsoft"`
+ * with a `MicrosoftAddAccountCredentials` payload.
  */
 export async function addAccountViaBroker(
   label: string,
   credentials: AddAccountCredentials,
-  opts: { replace?: boolean } = {},
+  opts: { replace?: boolean; provider?: ProviderName } = {},
 ): Promise<{ label: string; expiresAt?: number }> {
   const broker = new BrokerClient()
   try {
-    return await broker.addAccount(label, credentials, opts.replace)
+    return await broker.addAccount(
+      label,
+      credentials,
+      opts.replace,
+      opts.provider,
+    )
   } finally {
     await broker.close()
   }

package/telegram-plugin/gateway/auto-classify-mid-turn.ts

@@ -0,0 +1,119 @@
+/**
+ * auto-classify-mid-turn.ts — deterministic, model-free classification of a
+ * mid-turn inbound into STEER (amend the in-flight turn) vs QUEUE (new task),
+ * using TOPIC-vs-active-turn + reply-RECENCY as proxies for intent. No model
+ * inference: the gateway must decide at inbound time while the single CLI is
+ * busy.
+ *
+ * Today a no-prefix mid-turn message always QUEUES (the default flipped
+ * 2026-04-17 away from the blunt "everything steers" — see
+ * reference/steer-or-queue-mid-flight.md). This module is the basis for a
+ * smarter default. It ships first in SHADOW mode (the gateway logs what it WOULD
+ * decide but still queues), to gather real-world data — how often mid-turn
+ * messages are same-topic continuations vs cross-topic new tasks, and the
+ * recency distribution — before any behaviour flips on.
+ *
+ * Signal strength (be honest):
+ *  - TOPIC (supergroup): STRONG + structural. A message in a DIFFERENT forum
+ *    topic than the active turn is, by the supergroup-mode invariant, a separate
+ *    conversation → queue. This needs no timing guess.
+ *  - RECENCY: weaker. Within the same topic it cannot tell "also do X" (steer)
+ *    from "new question, same topic" (queue) — only a tight window + the
+ *    visible/correctable UX (the JTBD doc) makes auto-steer acceptable, and
+ *    that is gated separately. The recency clock is the agent's LAST OUTPUT
+ *    (msSinceLastAgentOutput), NOT turn age: a long actively-narrating worker
+ *    turn must not read "stale".
+ *  - DM: no topic at all → timing-only (the pre-2026-04-17 regime that
+ *    over-steered). DM auto-steer is OFF by default (window 0).
+ *
+ * Pure (no gateway imports) ⇒ unit-testable.
+ */
+
+export type MidTurnClass = 'steer' | 'queue'
+
+export type MidTurnReason =
+  | 'steer_prefix'
+  | 'queue_prefix'
+  | 'not_mid_turn'
+  | 'cross_topic'
+  | 'same_topic_recent'
+  | 'same_topic_stale'
+  | 'dm_recent'
+  | 'dm_disabled'
+  | 'topic_disabled'
+
+export interface AutoClassifyInput {
+  /** Explicit `/steer`|`/s` prefix present — the user's stated intent, authoritative. */
+  isSteerPrefix: boolean
+  /** Explicit `/queue`|`/q` prefix present. */
+  isQueuePrefix: boolean
+  /** Is a turn in flight for this chat/thread? (no → not our decision). */
+  priorTurnInFlight: boolean
+  /** DM (no forum topics) → timing-only. */
+  isDm: boolean
+  /** Incoming message's thread id (undefined/null in a DM). */
+  incomingThreadId: number | null | undefined
+  /** The in-flight turn's thread id (currentTurn.sessionThreadId). */
+  activeTurnThreadId: number | null | undefined
+  /** ms since the agent's LAST visible output in this chat/thread; null when no
+   *  output has been recorded (cold topic) → treated as not-recent. */
+  msSinceLastAgentOutput: number | null
+  /** Auto-steer recency window in a DM. 0 (default) = DM auto-steer OFF. */
+  dmSteerWindowMs: number
+  /** Auto-steer recency window in a supergroup topic. 0 = topic auto-steer OFF. */
+  topicSteerWindowMs: number
+}
+
+export interface AutoClassifyResult {
+  decision: MidTurnClass
+  reason: MidTurnReason
+  /** Whether the incoming message is in the SAME thread as the active turn
+   *  (canonicalized). Undefined when not applicable (no prefix-free mid-turn). */
+  sameTopic?: boolean
+}
+
+/** Canonical thread compare, matching chatKey's collapse (null/undefined/0 → same
+ *  "no-thread" bucket) — never raw === on raw ids (the silence-poke key-mismatch
+ *  bug class). */
+function sameThread(a: number | null | undefined, b: number | null | undefined): boolean {
+  const norm = (t: number | null | undefined): number | null => (t == null || t === 0 ? null : t)
+  return norm(a) === norm(b)
+}
+
+/**
+ * Classify a mid-turn inbound. Precedence: explicit prefix → not-mid-turn →
+ * DM(timing) / supergroup(topic then timing). Defaults bias to QUEUE (the safe,
+ * reversible, current behaviour); STEER only on a strong/recent signal AND its
+ * window enabled.
+ */
+export function autoClassifyMidTurnInbound(i: AutoClassifyInput): AutoClassifyResult {
+  // Explicit prefixes always win — the user's stated intent is authoritative.
+  if (i.isSteerPrefix) return { decision: 'steer', reason: 'steer_prefix' }
+  if (i.isQueuePrefix) return { decision: 'queue', reason: 'queue_prefix' }
+  // No turn in flight → caller starts a fresh turn (not a steer/queue decision).
+  if (!i.priorTurnInFlight) return { decision: 'queue', reason: 'not_mid_turn' }
+
+  const recent =
+    i.msSinceLastAgentOutput != null && i.msSinceLastAgentOutput >= 0
+
+  if (i.isDm) {
+    // DM: no topic → timing-only. Default OFF (dmSteerWindowMs 0).
+    if (i.dmSteerWindowMs <= 0) return { decision: 'queue', reason: 'dm_disabled' }
+    return recent && i.msSinceLastAgentOutput! <= i.dmSteerWindowMs
+      ? { decision: 'steer', reason: 'dm_recent' }
+      : { decision: 'queue', reason: 'dm_disabled' }
+  }
+
+  // Supergroup: topic identity is the PRIMARY signal.
+  const topicMatch = sameThread(i.incomingThreadId, i.activeTurnThreadId)
+  if (i.topicSteerWindowMs <= 0) {
+    return { decision: 'queue', reason: 'topic_disabled', sameTopic: topicMatch }
+  }
+  // Different topic than the in-flight turn → ALWAYS queue (a separate
+  // conversation; never steer it into the wrong topic's turn).
+  if (!topicMatch) return { decision: 'queue', reason: 'cross_topic', sameTopic: false }
+  // Same topic: steer only if recent enough; else a new question → queue.
+  return recent && i.msSinceLastAgentOutput! <= i.topicSteerWindowMs
+    ? { decision: 'steer', reason: 'same_topic_recent', sameTopic: true }
+    : { decision: 'queue', reason: 'same_topic_stale', sameTopic: true }
+}

package/telegram-plugin/gateway/escalation-drive.ts

@@ -0,0 +1,79 @@
+/**
+ * escalation-drive.ts — the obligation-ledger escalation step, extracted from
+ * obligationSweep so the hang → bounded → terminal behaviour is EXECUTABLE in a
+ * test with a fake hanging send. That path is unreachable by the two harnesses
+ * we have: mtcute can't make Telegram's API hang, and the synchronous property
+ * test can't model a promise that never settles — yet it is exactly the path the
+ * total proof flagged as the determinism hole. This file makes the real drive
+ * logic the sweep uses testable in isolation (escalation-drive.test.ts), so the
+ * fix is verified by execution, not only by reasoning + review.
+ *
+ * Invariant it upholds: a single escalation attempt
+ *  - is guarded so a sweep tick cannot fire a second concurrent send for the
+ *    same obligation while one is awaiting;
+ *  - bounds the send with `withDeadline`, so the chain ALWAYS settles within
+ *    `deadlineMs` ⇒ the in-flight flag ALWAYS clears (a hung send becomes a
+ *    bounded reject, handled like any other failed attempt);
+ *  - closes the obligation ONLY after a successful send; a transient failure
+ *    leaves it OPEN (retried next sweep); a permanent failure
+ *    (attempt ≥ maxAttempts) closes best-effort — so repeated hung/failed sends
+ *    reach a terminal in a bounded number of sweeps, never an infinite loop.
+ */
+import { withDeadline } from './with-deadline.js'
+
+/** The slice of the ledger the escalation step needs. */
+export interface EscalationLedger {
+  markEscalateAttempt(originTurnId: string): number
+  close(originTurnId: string | null | undefined): boolean
+}
+
+export interface DriveEscalationArgs {
+  escId: string
+  /** Set of origin ids with an escalation send in flight (concurrency guard). */
+  inFlight: Set<string>
+  ledger: EscalationLedger
+  /** Perform the operator-nudge send (already thread-fallback-wrapped). May hang. */
+  send: () => Promise<unknown>
+  /** Attempts before a permanent failure closes best-effort. */
+  maxAttempts: number
+  /** Bound on a single send so a hang can't leak the in-flight flag. */
+  deadlineMs: number
+  log?: (line: string) => void
+  /** Injectable for tests; defaults to the real withDeadline. */
+  withDeadlineFn?: typeof withDeadline
+}
+
+/**
+ * Drive one escalation attempt. Returns the settling chain promise (so tests can
+ * await it) or `undefined` if the call was a no-op because a send is already in
+ * flight for `escId`. obligationSweep calls this as `void driveEscalation(...)`.
+ */
+export function driveEscalation(args: DriveEscalationArgs): Promise<void> | undefined {
+  const { escId, inFlight, ledger, send, maxAttempts, deadlineMs } = args
+  const log = args.log ?? ((l: string) => process.stderr.write(l))
+  const wd = args.withDeadlineFn ?? withDeadline
+  if (inFlight.has(escId)) return undefined // a send is already awaiting
+  const attempt = ledger.markEscalateAttempt(escId)
+  inFlight.add(escId)
+  log(`telegram gateway: obligation escalating origin=${escId} attempt=${attempt}/${maxAttempts}\n`)
+  return wd(send(), deadlineMs, 'obligation escalation send timed out')
+    .then(() => {
+      ledger.close(escId)
+      log(`telegram gateway: obligation escalation delivered + closed origin=${escId}\n`)
+    })
+    .catch((err: unknown) => {
+      if (attempt >= maxAttempts) {
+        ledger.close(escId)
+        log(
+          `telegram gateway: obligation escalation PERMANENTLY undeliverable after ${attempt} attempts — closing best-effort origin=${escId}: ${err}\n`,
+        )
+      } else {
+        log(
+          `telegram gateway: obligation escalation send failed (attempt ${attempt}/${maxAttempts}), retrying next sweep origin=${escId}: ${err}\n`,
+        )
+      }
+    })
+    .finally(() => {
+      inFlight.delete(escId)
+    })
+}