switchroom 0.14.61 → 0.14.63

package/telegram-plugin/tests/microsoft-connect-flow.test.ts

@@ -0,0 +1,185 @@
+import { describe, it, expect } from 'vitest'
+
+import {
+  startMicrosoftConnect,
+  runMicrosoftConnectPoll,
+} from '../gateway/microsoft-connect-flow.js'
+import { DEFAULT_MICROSOFT_CLIENT_ID } from '../../src/auth/default-oauth-clients.js'
+import type {
+  MicrosoftDeviceCodeResponse,
+  MicrosoftOAuthClientConfig,
+  MicrosoftTokenResponse,
+} from '../../src/microsoft/oauth.js'
+
+const PERSONAL_MSA_TID = '9188040d-6c67-4c5b-b112-36a304b66dad'
+
+const DEVICE: MicrosoftDeviceCodeResponse = {
+  device_code: 'dc-abc',
+  user_code: 'ABCD-EFGH',
+  verification_uri: 'https://microsoft.com/devicelogin',
+  expires_in: 900,
+  interval: 5,
+}
+
+function fakeIdToken(payload: Record<string, unknown>): string {
+  const b64 = (o: unknown) => Buffer.from(JSON.stringify(o)).toString('base64url')
+  return `${b64({ alg: 'none' })}.${b64(payload)}.sig`
+}
+
+describe('startMicrosoftConnect', () => {
+  it('uses the shipped default client_id + default scopes when there is no config', async () => {
+    let seen: MicrosoftOAuthClientConfig | undefined
+    const res = await startMicrosoftConnect({
+      requestDeviceCode: async (cfg) => {
+        seen = cfg
+        return DEVICE
+      },
+    })
+    expect(res.kind).toBe('started')
+    if (res.kind === 'started') {
+      expect(res.source).toBe('default')
+      expect(res.clientId).toBe(DEFAULT_MICROSOFT_CLIENT_ID)
+      expect(res.scopes).toContain('offline_access')
+      expect(res.device.user_code).toBe('ABCD-EFGH')
+    }
+    expect(seen?.client_id).toBe(DEFAULT_MICROSOFT_CLIENT_ID)
+  })
+
+  it('refuses a vaulted BYO client (gateway can\'t resolve vault refs)', async () => {
+    const res = await startMicrosoftConnect({
+      configClientId: 'vault:microsoft-oauth-client-id',
+      requestDeviceCode: async () => DEVICE,
+    })
+    expect(res.kind).toBe('byo-vault')
+    if (res.kind === 'byo-vault') {
+      expect(res.ref).toBe('vault:microsoft-oauth-client-id')
+    }
+  })
+
+  it('uses a literal BYO config client_id (source=config)', async () => {
+    const res = await startMicrosoftConnect({
+      configClientId: 'byo-literal-123',
+      requestDeviceCode: async () => DEVICE,
+    })
+    expect(res.kind).toBe('started')
+    if (res.kind === 'started') {
+      expect(res.source).toBe('config')
+      expect(res.clientId).toBe('byo-literal-123')
+    }
+  })
+
+  it('returns an error when the device-code request fails', async () => {
+    const res = await startMicrosoftConnect({
+      requestDeviceCode: async () => {
+        throw new Error('device_code request failed (400): boom')
+      },
+    })
+    expect(res.kind).toBe('error')
+    if (res.kind === 'error') expect(res.message).toContain('boom')
+  })
+})
+
+describe('runMicrosoftConnectPoll', () => {
+  const flow = {
+    device: DEVICE,
+    clientId: 'client-1',
+    scopes: ['offline_access', 'Mail.ReadWrite'],
+    cancelled: false,
+  }
+
+  function tokens(o: Partial<MicrosoftTokenResponse> = {}): MicrosoftTokenResponse {
+    return {
+      access_token: 'at',
+      refresh_token: 'rt',
+      expires_in: 3600,
+      token_type: 'Bearer',
+      scope: 'Mail.ReadWrite',
+      ...o,
+    }
+  }
+
+  it('connects: registers the account via the broker keyed by the authenticated email', async () => {
+    const id_token = fakeIdToken({
+      tid: PERSONAL_MSA_TID,
+      oid: 'oid-1',
+      preferred_username: 'Lisa@Outlook.com',
+    })
+    const calls: Array<{ label: string; opts: unknown; refreshToken: string }> = []
+    const res = await runMicrosoftConnectPoll(flow, {
+      pollDeviceToken: async () => tokens({ id_token }),
+      addAccount: async (label, creds, opts) => {
+        calls.push({
+          label,
+          opts,
+          refreshToken: creds.microsoftOauth.refreshToken,
+        })
+        return { label }
+      },
+    })
+    expect(res.kind).toBe('connected')
+    if (res.kind === 'connected') {
+      expect(res.account).toBe('lisa@outlook.com')
+      expect(res.accountType).toBe('personal')
+    }
+    expect(calls).toHaveLength(1)
+    expect(calls[0].label).toBe('lisa@outlook.com')
+    expect(calls[0].opts).toEqual({ provider: 'microsoft', replace: true })
+    expect(calls[0].refreshToken).toBe('rt')
+  })
+
+  it('cancelled: does NOT register if the flow was cancelled during the poll', async () => {
+    let added = false
+    const res = await runMicrosoftConnectPoll(
+      { ...flow, cancelled: true },
+      {
+        pollDeviceToken: async () => tokens(),
+        addAccount: async () => {
+          added = true
+          return { label: 'x' }
+        },
+      },
+    )
+    expect(res.kind).toBe('cancelled')
+    expect(added).toBe(false)
+  })
+
+  it('no-refresh-token: refuses to register an un-refreshable account', async () => {
+    let added = false
+    const res = await runMicrosoftConnectPoll(flow, {
+      pollDeviceToken: async () => tokens({ refresh_token: undefined }),
+      addAccount: async () => {
+        added = true
+        return { label: 'x' }
+      },
+    })
+    expect(res.kind).toBe('no-refresh-token')
+    expect(added).toBe(false)
+  })
+
+  it('failed: surfaces a poll error (e.g. a work account rejected at /common)', async () => {
+    const res = await runMicrosoftConnectPoll(flow, {
+      pollDeviceToken: async () => {
+        throw new Error('Token poll failed: AADSTS9001023 work account')
+      },
+      addAccount: async () => ({ label: 'x' }),
+    })
+    expect(res.kind).toBe('failed')
+    if (res.kind === 'failed') expect(res.message).toContain('AADSTS9001023')
+  })
+
+  it('failed: refuses to register when Microsoft returns no id_token (no account identity)', async () => {
+    let added = false
+    const res = await runMicrosoftConnectPoll(flow, {
+      // Has a refresh token but no id_token → no resolvable email to key
+      // the broker account by; must NOT register a label-less account.
+      pollDeviceToken: async () => tokens({ id_token: undefined }),
+      addAccount: async () => {
+        added = true
+        return { label: 'x' }
+      },
+    })
+    expect(res.kind).toBe('failed')
+    if (res.kind === 'failed') expect(res.message).toContain('account identity')
+    expect(added).toBe(false)
+  })
+})

package/telegram-plugin/tests/obligation-determinism.test.ts

@@ -7,30 +7,30 @@ import {
 } from "../gateway/obligation-store.js";
 
 /**
- * DETERMINISM PROOF (by exhaustive simulation, not live observation).
+ * REGRESSION GUARD — not the proof.
  *
- * The operator's requirement: be confident — by reasoning — that EVERY real
- * inbound reaches answered-or-escalated for ANY model behaviour and ANY timing,
- * including across a restart, with no silent drop and no double-ask of a message
- * that WAS answered.
+ * The actual determinism argument is closed-form and lives WITH the code: the
+ * ledger is a finite FSM with a total transition function and a strictly-
+ * decreasing measure μ = (REPRESENT_MAX - representCount) + (ESCALATE_MAX -
+ * escalateAttempts) ⇒ every OPEN reaches a terminal (see the proof comment on
+ * obligationSweep in gateway.ts and the ledger methods in obligation-ledger.ts).
+ * A total state-machine proof also found — and a fix closed — the one liveness
+ * hole this kind of SAMPLING test structurally cannot reach: a hung escalation
+ * send leaking the in-flight flag (now bounded by withDeadline; guarded by
+ * with-deadline.test.ts). The lesson stands: a random-schedule test only
+ * exercises the behaviours its model encodes; it is evidence, never the proof.
  *
- * This drives the REAL ObligationLedger + the REAL durable snapshot store
- * (obligation-store, over an in-memory fs whose rename is atomic) through a
- * faithful model of the gateway's obligation lifecycle:
- *
- *   OPEN     — on receipt (handleInbound, idempotent).
- *   close    — at turn_end iff the turn delivered a final answer (finalAnswerDelivered).
- *   represent— idle sweep, bounded by maxRepresents, drives a fresh must-answer turn.
- *   escalate — ladder exhausted: send the operator nudge; close ONLY after it
- *              lands; a transient send failure stays OPEN and retries; a permanent
- *              one is bounded (OBLIGATION_ESCALATE_MAX) → close best-effort.
- *   restart  — fresh ledger hydrated from the durable snapshot (counters intact).
- *
- * Over thousands of random schedules it asserts the invariant holds and the
- * engine always terminates (no infinite loop). The COALESCED PARTIAL-ANSWER
- * residual is deliberately NOT modelled — it is the one honest hard limit (a
- * turn-keyed ledger cannot see "answered half" without parsing model prose) and
- * is mitigated by coalescing policy, not the ledger.
+ * What this file still earns its keep doing: drive the REAL ObligationLedger +
+ * REAL durable snapshot store over many random {model-behaviour × timing ×
+ * restart} schedules to catch a regression that breaks the FSM invariant
+ * (no silent drop, no double-ask of an answered message, bounded termination).
+ * It models the lifecycle SYNCHRONOUSLY (open at receipt; close at turn_end on a
+ * delivered answer; bounded represent→escalate; restart = hydrate from snapshot)
+ * — so it does NOT and cannot cover async/coupling liveness (hung send, gate
+ * never opening, drain wedging); those are proven/bounded in the code, not here.
+ * The coalesced PARTIAL-ANSWER residual is also out of model — the one honest
+ * hard limit (a turn-keyed ledger can't see "answered half" without parsing the
+ * model's prose), mitigated by coalescing policy, not the ledger.
  */
 
 // Mirrors the gateway constants under test.
@@ -89,12 +89,18 @@ interface Sim {
   steps: number;
 }
 
-function runSchedule(msgs: Msg[], seed: number): Sim {
+function runSchedule(msgs: Msg[], seed: number, graceMs = 0): Sim {
   const PATH = "/state/agent/telegram/obligations.json";
   const store = memStore();
   let ledger = new ObligationLedger(MAX_REPRESENTS, {
     onChange: (snap) => persistObligations(PATH, store.fs, snap),
   });
+  // Virtual monotonic clock (only meaningful when graceMs>0). Advances every
+  // step by more than one sweep tick so the grace window deterministically
+  // expires within the step budget — proving grace DELAYS but never PREVENTS a
+  // terminal (no livelock).
+  let clock = 1_000_000;
+  const SWEEP_TICK = 5_000;
   const r = rng(seed);
 
   const pending = [...msgs]; // not yet received
@@ -109,11 +115,18 @@ function runSchedule(msgs: Msg[], seed: number): Sim {
   };
 
   // Run one turn for an obligation; close if the model answers on this attempt.
+  // If it does NOT answer and grace is on, stamp the turn-end clock (mirrors the
+  // gateway's endCurrentTurnAtomic !finalAnswerDelivered branch) so the next
+  // decideAtIdle({now, graceMs}) waits out the grace before re-presenting.
   const deliverTurn = (id: string) => {
     const had = (turnsHad.get(id) ?? 0);
     const attemptIndex = had; // 0-based
     turnsHad.set(id, had + 1);
-    if (byId.get(id)!.answerOnAttempt === attemptIndex) close(id, "answered");
+    if (byId.get(id)!.answerOnAttempt === attemptIndex) {
+      close(id, "answered");
+    } else if (graceMs > 0 && ledger.isOpen(id)) {
+      ledger.noteTurnEnded(id, clock);
+    }
   };
 
   const ESC_IN_FLIGHT = new Set<string>(); // mirrors the gateway's concurrency guard (no-op in a sync model)
@@ -139,7 +152,14 @@ function runSchedule(msgs: Msg[], seed: number): Sim {
       });
       deliverTurn(m.id); // original turn (attempt 0)
     } else if (open) {
-      const decision = ledger.decideAtIdle();
+      const decision =
+        graceMs > 0 ? ledger.decideAtIdle({ now: clock, graceMs }) : ledger.decideAtIdle();
+      if (decision.action === "none") {
+        // Every open obligation is within its grace window — the sweep waits.
+        // Advance the clock so grace deterministically expires; no livelock.
+        clock += SWEEP_TICK;
+        continue;
+      }
       const o = decision.obligation as Obligation;
       // INVARIANT (no double-ask): a terminated obligation must never resurface.
       expect(terminals.has(o.originTurnId)).toBe(false);
@@ -169,6 +189,9 @@ function runSchedule(msgs: Msg[], seed: number): Sim {
       });
       ledger.hydrate(loadObligations(PATH, store.fs));
     }
+    // Advance the virtual clock every step so any stamped grace window
+    // deterministically expires within the step budget.
+    clock += SWEEP_TICK;
   }
 
   return { terminals, steps };
@@ -220,6 +243,43 @@ describe("obligation determinism — every inbound reaches a terminal, no silent
     }
   });
 
+  it("holds across 3000 schedules WITH the escalate-grace window on (grace delays, never prevents a terminal)", () => {
+    const ANSWER = [0, 1, 2, 3, 99];
+    const ESCFAIL = [0, 1, 2, 3, 5];
+    const GRACE_MS = 45_000;
+    for (let seed = 1; seed <= 3000; seed++) {
+      const r = rng(seed * 7919);
+      const n = 1 + Math.floor(r() * 5);
+      const msgs: Msg[] = [];
+      for (let i = 0; i < n; i++) {
+        const msgId = seed * 100 + i;
+        msgs.push({
+          id: `c:3#${msgId}`,
+          msgId,
+          answerOnAttempt: pick(ANSWER, r),
+          escalateFailsFor: pick(ESCFAIL, r),
+        });
+      }
+      // Same enumeration as the no-grace proof, but the ledger now runs the grace
+      // path: every non-answering turn stamps noteTurnEnded and the sweep waits
+      // out the window before acting. The terminal each message reaches must be
+      // IDENTICAL to the no-grace run — grace only delays.
+      const { terminals, steps } = runSchedule(msgs, seed * 104729, GRACE_MS);
+      expect(steps).toBeLessThan(10_000); // still terminates (no grace livelock)
+      for (const m of msgs) {
+        const t = terminals.get(m.id);
+        expect(t, `grace seed=${seed} msg=${m.id} answer=${m.answerOnAttempt} escFail=${m.escalateFailsFor}`).toBeDefined();
+        if (m.answerOnAttempt <= MAX_REPRESENTS) {
+          expect(t).toBe("answered");
+        } else if (m.escalateFailsFor < ESCALATE_MAX) {
+          expect(t).toBe("escalation-delivered");
+        } else {
+          expect(t).toBe("escalation-give-up");
+        }
+      }
+    }
+  });
+
   it("a delivered-but-unanswered obligation survives a restart and is escalated, not lost", () => {
     // Deterministic single case: model NEVER answers, escalation succeeds first try,
     // with a restart forced mid-life via a seed that triggers the 0.15 branch.

package/telegram-plugin/tests/obligation-ledger.test.ts

@@ -225,6 +225,20 @@ describe("ObligationLedger — durability hooks + escalate-attempt counter", ()
     expect(L.decideAtIdle().action).toBe("escalate");
   });
 
+  it("interrupt-cancel semantics: closing the in-flight turn's obligation removes it from the sweep, sibling untouched", () => {
+    // Mirrors cancelInterruptedObligation: an `!` interrupt SIGINT-kills the
+    // in-flight turn and closes its obligation, so the sweep can't later
+    // re-present/escalate the question the user explicitly redirected away from.
+    // A queued SIBLING obligation must survive.
+    const L = new ObligationLedger();
+    L.openIfAbsent(input("c:3#700", 1000)); // the in-flight turn's message
+    L.openIfAbsent(input("c:3#701", 1001)); // a queued sibling
+    expect(L.close("c:3#700")).toBe(true); // interrupt cancels the in-flight one
+    expect(L.isOpen("c:3#700")).toBe(false);
+    expect(L.decideAtIdle().obligation?.originTurnId).toBe("c:3#701"); // sibling still actionable
+    expect(L.close("c:3#700")).toBe(false); // re-close / unknown is a safe no-op
+  });
+
   it("hydrate skips malformed rows", () => {
     const L = new ObligationLedger();
     L.hydrate([
@@ -234,3 +248,81 @@ describe("ObligationLedger — durability hooks + escalate-attempt counter", ()
     expect(L.size()).toBe(1);
   });
 });
+
+describe("ObligationLedger — escalate-grace window (over-escalation fix)", () => {
+  function input(id: string, openedAt: number) {
+    return { originTurnId: id, chatId: "-100123", threadId: 3, messageId: Number(id.split("#").pop() ?? 0), text: "x", openedAt };
+  }
+
+  it("no opts (or graceMs<=0) → pre-grace behaviour: acts immediately", () => {
+    const L = new ObligationLedger();
+    L.openIfAbsent(input("c:3#1", 1000));
+    L.noteTurnEnded("c:3#1", 5000); // a turn just ended
+    expect(L.decideAtIdle().action).toBe("represent"); // no grace → act now
+    expect(L.decideAtIdle({ now: 5001, graceMs: 0 }).action).toBe("represent"); // graceMs 0 → off
+  });
+
+  it("skips an obligation whose turn ended < graceMs ago (the trailing-answer window)", () => {
+    const L = new ObligationLedger();
+    L.openIfAbsent(input("c:3#1", 1000));
+    L.noteTurnEnded("c:3#1", 5000);
+    // 30s after turn-end, grace 45s → still within grace → wait (none)
+    expect(L.decideAtIdle({ now: 35000, graceMs: 45000 }).action).toBe("none");
+    // 46s after turn-end → out of grace → act
+    expect(L.decideAtIdle({ now: 51000, graceMs: 45000 }).action).toBe("represent");
+  });
+
+  it("an obligation that never had a turn end (still-queued) is always eligible — no trailing answer to wait for", () => {
+    const L = new ObligationLedger();
+    L.openIfAbsent(input("c:3#1", 1000)); // no noteTurnEnded
+    expect(L.decideAtIdle({ now: 1001, graceMs: 45000 }).action).toBe("represent");
+  });
+
+  it("picks the oldest ELIGIBLE: a newer in-grace obligation does not block an older out-of-grace one", () => {
+    const L = new ObligationLedger();
+    L.openIfAbsent(input("c:3#1", 1000)); // older
+    L.openIfAbsent(input("c:3#2", 2000)); // newer
+    L.noteTurnEnded("c:3#1", 5000); // older's turn ended at 5000 (out of grace by now)
+    L.noteTurnEnded("c:3#2", 60000); // newer's turn ended at 60000 (in grace)
+    const d = L.decideAtIdle({ now: 70000, graceMs: 45000 });
+    // older (#1) ended 65s ago → eligible; newer (#2) ended 10s ago → in grace.
+    // pick oldest eligible = #1.
+    expect(d.action).toBe("represent");
+    expect(d.obligation?.originTurnId).toBe("c:3#1");
+  });
+
+  it("returns none when EVERY open obligation is within grace", () => {
+    const L = new ObligationLedger();
+    L.openIfAbsent(input("c:3#1", 1000));
+    L.openIfAbsent(input("c:3#2", 2000));
+    L.noteTurnEnded("c:3#1", 60000);
+    L.noteTurnEnded("c:3#2", 61000);
+    expect(L.decideAtIdle({ now: 65000, graceMs: 45000 }).action).toBe("none");
+  });
+
+  it("noteTurnEnded is a no-op for an unknown/closed obligation and persists when it applies", () => {
+    const snapshots: Obligation[][] = [];
+    const L = new ObligationLedger(2, { onChange: (s) => snapshots.push(s) });
+    L.openIfAbsent(input("c:3#1", 1000)); // persist #1
+    L.noteTurnEnded("nope", 5000); // unknown → no persist
+    expect(snapshots.length).toBe(1);
+    L.noteTurnEnded("c:3#1", 5000); // applies → persist
+    expect(snapshots.length).toBe(2);
+    expect(snapshots[1][0].lastTurnEndedAt).toBe(5000);
+  });
+
+  it("grace still terminates the ladder: represent → escalate once each is out of grace", () => {
+    const L = new ObligationLedger(2);
+    L.openIfAbsent(input("c:3#1", 1000));
+    // turn 0 ended at 1000; out of grace by t=50000
+    L.noteTurnEnded("c:3#1", 1000);
+    expect(L.decideAtIdle({ now: 50000, graceMs: 45000 }).action).toBe("represent");
+    L.markRepresented("c:3#1");
+    L.noteTurnEnded("c:3#1", 50000); // re-present turn ended
+    expect(L.decideAtIdle({ now: 96000, graceMs: 45000 }).action).toBe("represent");
+    L.markRepresented("c:3#1");
+    L.noteTurnEnded("c:3#1", 96000);
+    // representCount now 2 == max → escalate (once out of grace)
+    expect(L.decideAtIdle({ now: 142000, graceMs: 45000 }).action).toBe("escalate");
+  });
+});

package/telegram-plugin/tests/with-deadline.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from "vitest";
+import { withDeadline } from "../gateway/with-deadline.js";
+
+const tick = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+describe("withDeadline — bounds the obligation escalation send so a hang can't leak the in-flight flag", () => {
+  it("resolves with the inner value when the promise settles before the deadline", async () => {
+    await expect(withDeadline(Promise.resolve("ok"), 1000, "timed out")).resolves.toBe("ok");
+  });
+
+  it("rejects with the inner error when the promise rejects before the deadline", async () => {
+    await expect(withDeadline(Promise.reject(new Error("boom")), 1000, "timed out")).rejects.toThrow(
+      "boom",
+    );
+  });
+
+  it("rejects with the timeout message when the promise NEVER settles (the hang case)", async () => {
+    // The whole point: a promise that never resolves/rejects (a stalled send)
+    // must still settle the chain so the caller's .finally clears the in-flight flag.
+    const neverSettles = new Promise<string>(() => {});
+    await expect(withDeadline(neverSettles, 20, "obligation escalation send timed out")).rejects.toThrow(
+      "obligation escalation send timed out",
+    );
+  });
+
+  it("the .finally chained after it ALWAYS runs even when the inner promise hangs", async () => {
+    // This mirrors the gateway's obligationEscalateInFlight clear: it lives in a
+    // .finally on withDeadline(...), and must fire within the deadline regardless.
+    let flagCleared = false;
+    await withDeadline(new Promise<void>(() => {}), 20, "timed out")
+      .catch(() => {})
+      .finally(() => {
+        flagCleared = true;
+      });
+    expect(flagCleared).toBe(true);
+  });
+
+  it("a hung-then-late-rejecting inner promise does not produce an unhandled rejection", async () => {
+    const seen: unknown[] = [];
+    const onUnhandled = (reason: unknown) => seen.push(reason);
+    process.on("unhandledRejection", onUnhandled);
+    try {
+      const lateReject = new Promise<void>((_, reject) => {
+        setTimeout(() => reject(new Error("late-zombie-rejection")), 30);
+      });
+      // withDeadline rejects at 10ms; the inner promise rejects later at 30ms.
+      await withDeadline(lateReject, 10, "timed out").catch(() => {});
+      await tick(60); // let the late rejection fire
+    } finally {
+      process.off("unhandledRejection", onUnhandled);
+    }
+    expect(seen.some((r) => r instanceof Error && r.message === "late-zombie-rejection")).toBe(false);
+  });
+
+  it("clears its timer on a fast settle (no dangling work keeps the loop alive)", async () => {
+    // Sanity: a fast resolve settles immediately, not after the deadline.
+    const start = Date.now();
+    await withDeadline(Promise.resolve(1), 5000, "timed out");
+    expect(Date.now() - start).toBeLessThan(500);
+  });
+});