switchroom 0.12.28 → 0.12.29

package/dist/cli/switchroom.js

@@ -47247,8 +47247,8 @@ var {
 } = import__.default;
 
 // src/build-info.ts
-var VERSION = "0.12.28";
-var COMMIT_SHA = "61036e48";
+var VERSION = "0.12.29";
+var COMMIT_SHA = "f7c92422";
 
 // src/cli/agent.ts
 init_source();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.12.28",
+  "version": "0.12.29",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {

package/telegram-plugin/dist/gateway/gateway.js

@@ -44203,6 +44203,53 @@ function dispatchOne(effect, ctx) {
   }
 }
 
+// gateway/prefix-warmup.ts
+var WARMUP_COOLDOWN_MS = 5 * 60000;
+var lastWarmupAtPerAgent = new Map;
+var WARMUP_TEXT = `__WARMUP_PING__
+
+This is a system prefix-cache warmup (not from a user). ` + "Respond with exactly `NO_REPLY` and nothing else. " + "The gateway will suppress the response \u2014 no message will be sent to anyone.";
+function maybeFireWarmup(ctx) {
+  if (process.env.SWITCHROOM_PREFIX_WARMUP !== "1")
+    return false;
+  const log = ctx.log ?? ((line) => process.stderr.write(line));
+  const now = (ctx.now ?? Date.now)();
+  const lastAt = lastWarmupAtPerAgent.get(ctx.selfAgent) ?? 0;
+  if (now - lastAt < WARMUP_COOLDOWN_MS) {
+    log(`telegram gateway: prefix-warmup skipped agent=${ctx.selfAgent} ` + `reason=cooldown last=${Math.round((now - lastAt) / 1000)}s ago
+`);
+    return false;
+  }
+  const target = ctx.resolveBootTarget();
+  if (!target) {
+    log(`telegram gateway: prefix-warmup skipped agent=${ctx.selfAgent} ` + `reason=no-boot-chat-target
+`);
+    return false;
+  }
+  const msg = {
+    type: "inbound",
+    chatId: target.chatId,
+    ...target.threadId !== undefined ? { threadId: target.threadId } : {},
+    messageId: 0,
+    user: "switchroom-warmup",
+    userId: 0,
+    ts: Math.floor(now / 1000),
+    text: WARMUP_TEXT,
+    meta: { source: "warmup" }
+  };
+  try {
+    ctx.client.send(msg);
+    lastWarmupAtPerAgent.set(ctx.selfAgent, now);
+    log(`telegram gateway: prefix-warmup fired agent=${ctx.selfAgent} ` + `chat=${target.chatId} thread=${target.threadId ?? "-"}
+`);
+    return true;
+  } catch (err) {
+    log(`telegram gateway: prefix-warmup send threw agent=${ctx.selfAgent}: ` + `${err.message}
+`);
+    return false;
+  }
+}
+
 // gateway/vault-grant-inbound-builders.ts
 function buildVaultGrantApprovedInbound(opts) {
   const ts = opts.nowMs ?? Date.now();
@@ -47515,11 +47562,11 @@ function sweepStaleTurnActiveMarker(stateDir, opts) {
 }
 
 // ../src/build-info.ts
-var VERSION = "0.12.28";
-var COMMIT_SHA = "61036e48";
-var COMMIT_DATE = "2026-05-20T14:43:34Z";
-var LATEST_PR = 1592;
-var COMMITS_AHEAD_OF_TAG = 4;
+var VERSION = "0.12.29";
+var COMMIT_SHA = "f7c92422";
+var COMMIT_DATE = "2026-05-20T15:44:41Z";
+var LATEST_PR = 1595;
+var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts
 function formatRelativeAgo(iso) {
@@ -48468,8 +48515,9 @@ function statusKey(chatId, threadId) {
 function streamKey3(chatId, threadId) {
   return chatKey(chatId, threadId);
 }
-function purgeReactionTracking(key) {
-  shadowEmit({ kind: "turnEnd", key, at: Date.now(), outboundEmitted: true });
+function purgeReactionTracking(key, endingTurn) {
+  const outboundEmitted = endingTurn != null ? endingTurn.replyCalled === true : currentTurn?.replyCalled === true;
+  shadowEmit({ kind: "turnEnd", key, at: Date.now(), outboundEmitted });
   const msgInfo = activeReactionMsgIds.get(key);
   activeStatusReactions.delete(key);
   activeReactionMsgIds.delete(key);
@@ -48502,7 +48550,7 @@ function endCurrentTurnAtomic(turn) {
   if (currentTurn !== turn)
     return;
   currentTurn = null;
-  purgeReactionTracking(statusKey(turn.sessionChatId, turn.sessionThreadId));
+  purgeReactionTracking(statusKey(turn.sessionChatId, turn.sessionThreadId), turn);
 }
 function maybeProactiveCompact() {
   if (compactDispatching)
@@ -49427,6 +49475,20 @@ var ipcServer = createIpcServer({
         }
       }
     }
+    if (client3.agentName != null) {
+      maybeFireWarmup({
+        selfAgent: client3.agentName,
+        client: client3,
+        resolveBootTarget: () => {
+          const marker = readRestartMarker();
+          const ageMs = marker ? Date.now() - marker.ts : undefined;
+          const target = resolveBootChatId(marker, ageMs);
+          if (!target)
+            return null;
+          return { chatId: target.chatId, threadId: target.threadId };
+        }
+      });
+    }
     const dedupeDecision = shouldSkipDuplicateBootCard({ activeBootCard, bootCardPending }, "bridge-reconnect");
     if (dedupeDecision.skip) {
       process.stderr.write(`telegram gateway: bridge-reconnect: skipping boot card (${dedupeDecision.reason})

package/telegram-plugin/gateway/gateway.ts

@@ -263,6 +263,7 @@ import { chatKey, chatKeyWithSuffix } from './chat-key.js'
 import { shadowEmit } from './inbound-delivery-machine-shadow.js'
 import type { ChatKey as _ChatKey } from './inbound-delivery-machine.js'
 import { dispatchEffects, isDispatchEnabled } from './inbound-delivery-machine-dispatch.js'
+import { maybeFireWarmup } from './prefix-warmup.js'
 import {
   buildVaultGrantApprovedInbound,
   buildVaultGrantDeniedInbound,
@@ -1277,14 +1278,24 @@ function streamKey(chatId: string, threadId?: number | null): string {
   return chatKey(chatId, threadId)
 }
 
-function purgeReactionTracking(key: string): void {
-  // Phase 2b shadow: turn end. The key was registered via setTurnStarted
-  // when the inbound arrived; purge is the canonical turn-end signal.
-  // outboundEmitted is approximated `true` here — refined in PR 3 to read
-  // from the per-turn `replyCalled` flag on `currentTurn`. Conservative
-  // shadow approximation is safe (only affects machine's lastOutboundAt
-  // tracking; can't drive incorrect behavior in shadow mode).
-  shadowEmit({ kind: 'turnEnd', key: key as _ChatKey, at: Date.now(), outboundEmitted: true })
+function purgeReactionTracking(key: string, endingTurn?: CurrentTurn): void {
+  // Phase 2b: turn end. The key was registered via setTurnStarted when
+  // the inbound arrived; purge is the canonical turn-end signal.
+  //
+  // outboundEmitted: read from the explicit `endingTurn` parameter when
+  // provided (canonical path via endCurrentTurnAtomic — module-scope
+  // currentTurn is already null by the time we get here), falling back
+  // to `currentTurn?.replyCalled` for the legacy callsites that haven't
+  // been threaded yet (sibling-key purges, restart-init cleanup).
+  // Without this explicit-turn handoff the shadow trace would report
+  // outboundEmitted=false on every replied turn (the dominant happy
+  // path), producing strictly worse data than the blind `true` it
+  // replaced. Invariant #5's `lastOutboundAt` correctness depends on
+  // this signal being accurate.
+  const outboundEmitted = endingTurn != null
+    ? endingTurn.replyCalled === true
+    : currentTurn?.replyCalled === true
+  shadowEmit({ kind: 'turnEnd', key: key as _ChatKey, at: Date.now(), outboundEmitted })
   const msgInfo = activeReactionMsgIds.get(key)
   activeStatusReactions.delete(key)
   activeReactionMsgIds.delete(key)
@@ -1370,7 +1381,12 @@ function purgeReactionTracking(key: string): void {
 function endCurrentTurnAtomic(turn: CurrentTurn): void {
   if (currentTurn !== turn) return
   currentTurn = null
-  purgeReactionTracking(statusKey(turn.sessionChatId, turn.sessionThreadId))
+  // Pass `turn` so purgeReactionTracking sees the authoritative
+  // replyCalled flag even though we just nulled module-scope
+  // currentTurn. Without this, the shadow trace's outboundEmitted
+  // would be false on every replied turn (the dominant happy path),
+  // producing strictly worse data than the blind `true` it replaced.
+  purgeReactionTracking(statusKey(turn.sessionChatId, turn.sessionThreadId), turn)
 }
 
 /**
@@ -3267,6 +3283,28 @@ const ipcServer: IpcServer = createIpcServer({
       }
     }
 
+    // Prefix-cache warmup (cold-start TTFO RFC, opt-in via
+    // SWITCHROOM_PREFIX_WARMUP=1). Fires a synthetic inbound to claude
+    // BEFORE the user's next real message so Anthropic's prefix cache
+    // is warm on the user-perceived first turn. Gated, debounced
+    // (5-min cooldown per agent), and skipped if no boot chat resolves.
+    // Claude responds NO_REPLY per inline instruction; existing
+    // silent-marker suppression at gateway.ts:5906 swallows the
+    // outbound. See docs/rfcs/cold-start-ttfo.md Option A.
+    if (client.agentName != null) {
+      maybeFireWarmup({
+        selfAgent: client.agentName,
+        client,
+        resolveBootTarget: () => {
+          const marker = readRestartMarker()
+          const ageMs = marker ? Date.now() - marker.ts : undefined
+          const target = resolveBootChatId(marker, ageMs)
+          if (!target) return null
+          return { chatId: target.chatId, threadId: target.threadId }
+        },
+      })
+    }
+
     // If the agent reconnected after a /restart (or any restart), post a boot
     // card. The restart-marker carries the ack chat; if absent we fall back to
     // resolveBootChatId so crash-recovery reconnects also get a card.

package/telegram-plugin/gateway/prefix-warmup.ts

@@ -0,0 +1,123 @@
+/**
+ * Prefix-cache warmup turn — opt-in cold-start TTFO optimization.
+ *
+ * Per cold-start TTFO RFC (docs/rfcs/cold-start-ttfo.md, PR #1589),
+ * Option A. On every bridge-up after a restart, synthesize a synthetic
+ * inbound (`__WARMUP_PING__`, meta.source="warmup") and deliver it to
+ * the just-registered bridge. Claude processes the message — paying
+ * the full cold-cache cost on the synthetic turn — and responds
+ * `NO_REPLY` per the in-prompt instruction. The existing NO_REPLY
+ * suppression at `gateway.ts:5949` swallows the outbound.
+ *
+ * By the time the user's REAL next message arrives, Anthropic's prefix
+ * cache is warm and the user-perceived TTFO drops 4-8s on average.
+ *
+ * Phase 1 (this file): minimum-viable warmup. AGENT.md is NOT modified
+ * — the warmup TEXT carries the NO_REPLY instruction inline. Agent
+ * compliance is best-effort; non-compliant agents will emit a real
+ * reply to the primary chat (acceptable UX cost gated behind opt-in
+ * env var). Cooldown prevents the gymbro-style bridge-churn case from
+ * burning OAuth quota on every flap.
+ *
+ * Kill switch: `SWITCHROOM_PREFIX_WARMUP=1` opt-in (default OFF).
+ *
+ * Future PR (Phase 2): suppress 👀 reaction + progress card for
+ * meta.source="warmup" inbound; tag for Hindsight exclusion.
+ */
+
+import type { IpcClient } from './ipc-server.js'
+import type { InboundMessage } from './ipc-protocol.js'
+
+// Per cold-start RFC open-question #4: cooldown anchored on bridge-up
+// time; conservative 5-minute window catches gymbro-style 6-reconnects-
+// per-UAT-cycle without dropping legitimate every-restart warmups.
+const WARMUP_COOLDOWN_MS = 5 * 60_000
+
+const lastWarmupAtPerAgent = new Map<string, number>()
+
+export const WARMUP_TEXT =
+  '__WARMUP_PING__\n\nThis is a system prefix-cache warmup (not from a user). ' +
+  'Respond with exactly `NO_REPLY` and nothing else. ' +
+  'The gateway will suppress the response — no message will be sent to anyone.'
+
+export interface WarmupCtx {
+  readonly selfAgent: string
+  readonly client: IpcClient
+  readonly resolveBootTarget: () =>
+    | { chatId: string; threadId?: number | undefined }
+    | null
+  readonly log?: (line: string) => void
+  readonly now?: () => number
+}
+
+/**
+ * Fire a prefix-cache warmup if conditions are met. Idempotent within
+ * the cooldown window. Returns true when a warmup was actually sent.
+ *
+ * Conditions:
+ *   1. `SWITCHROOM_PREFIX_WARMUP=1` env var set (opt-in).
+ *   2. Cooldown elapsed for this agent (default 5 min).
+ *   3. A boot chat target resolves (no point warming without a chat).
+ *
+ * The warmup is delivered to `client.send()` directly — it bypasses
+ * the gateway's `handleInbound`, which gates on a real Telegram
+ * Context object. The bridge forwards to claude exactly as it would a
+ * Telegram message.
+ */
+export function maybeFireWarmup(ctx: WarmupCtx): boolean {
+  if (process.env.SWITCHROOM_PREFIX_WARMUP !== '1') return false
+
+  const log = ctx.log ?? ((line: string) => process.stderr.write(line))
+  const now = (ctx.now ?? Date.now)()
+
+  const lastAt = lastWarmupAtPerAgent.get(ctx.selfAgent) ?? 0
+  if (now - lastAt < WARMUP_COOLDOWN_MS) {
+    log(
+      `telegram gateway: prefix-warmup skipped agent=${ctx.selfAgent} ` +
+        `reason=cooldown last=${Math.round((now - lastAt) / 1000)}s ago\n`,
+    )
+    return false
+  }
+
+  const target = ctx.resolveBootTarget()
+  if (!target) {
+    log(
+      `telegram gateway: prefix-warmup skipped agent=${ctx.selfAgent} ` +
+        `reason=no-boot-chat-target\n`,
+    )
+    return false
+  }
+
+  const msg: InboundMessage = {
+    type: 'inbound',
+    chatId: target.chatId,
+    ...(target.threadId !== undefined ? { threadId: target.threadId } : {}),
+    messageId: 0, // synthetic — never matches a real Telegram message
+    user: 'switchroom-warmup',
+    userId: 0,
+    ts: Math.floor(now / 1000),
+    text: WARMUP_TEXT,
+    meta: { source: 'warmup' },
+  }
+
+  try {
+    ctx.client.send(msg)
+    lastWarmupAtPerAgent.set(ctx.selfAgent, now)
+    log(
+      `telegram gateway: prefix-warmup fired agent=${ctx.selfAgent} ` +
+        `chat=${target.chatId} thread=${target.threadId ?? '-'}\n`,
+    )
+    return true
+  } catch (err) {
+    log(
+      `telegram gateway: prefix-warmup send threw agent=${ctx.selfAgent}: ` +
+        `${(err as Error).message}\n`,
+    )
+    return false
+  }
+}
+
+/** Test hook: reset the cooldown state. */
+export function __resetForTests(): void {
+  lastWarmupAtPerAgent.clear()
+}

package/telegram-plugin/tests/prefix-warmup.test.ts

@@ -0,0 +1,175 @@
+/**
+ * Tests for the prefix-cache warmup module.
+ *
+ * Per cold-start TTFO RFC Option A: fire a synthetic inbound on
+ * bridge-up so Anthropic's prefix cache is warm by the user's next
+ * real message. These tests pin: env gate, cooldown, missing-target
+ * skip, message shape (meta.source="warmup", correct text), and
+ * cooldown debounce across multiple bridge reconnects.
+ */
+
+import { describe, expect, it, beforeEach, vi } from 'vitest'
+import {
+  __resetForTests,
+  maybeFireWarmup,
+  WARMUP_TEXT,
+} from '../gateway/prefix-warmup'
+import type { WarmupCtx } from '../gateway/prefix-warmup'
+
+beforeEach(() => {
+  __resetForTests()
+  delete process.env.SWITCHROOM_PREFIX_WARMUP
+})
+
+function makeCtx(overrides?: Partial<WarmupCtx>): {
+  ctx: WarmupCtx
+  send: ReturnType<typeof vi.fn>
+  logs: string[]
+} {
+  const send = vi.fn()
+  const logs: string[] = []
+  const ctx: WarmupCtx = {
+    selfAgent: 'test-agent',
+    client: { send, agentName: 'test-agent', id: 'c1', isAlive: () => true, lastHeartbeat: 0, close: () => {} } as never,
+    resolveBootTarget: () => ({ chatId: '12345', threadId: undefined }),
+    log: (l: string) => logs.push(l),
+    now: () => 1_000_000,
+    ...overrides,
+  }
+  return { ctx, send, logs }
+}
+
+describe('maybeFireWarmup — env gate', () => {
+  it('skipped when SWITCHROOM_PREFIX_WARMUP is unset', () => {
+    const { ctx, send } = makeCtx()
+    expect(maybeFireWarmup(ctx)).toBe(false)
+    expect(send).not.toHaveBeenCalled()
+  })
+
+  it('skipped when SWITCHROOM_PREFIX_WARMUP is 0', () => {
+    process.env.SWITCHROOM_PREFIX_WARMUP = '0'
+    const { ctx, send } = makeCtx()
+    expect(maybeFireWarmup(ctx)).toBe(false)
+    expect(send).not.toHaveBeenCalled()
+  })
+
+  it('fires when SWITCHROOM_PREFIX_WARMUP=1', () => {
+    process.env.SWITCHROOM_PREFIX_WARMUP = '1'
+    const { ctx, send } = makeCtx()
+    expect(maybeFireWarmup(ctx)).toBe(true)
+    expect(send).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('maybeFireWarmup — message shape', () => {
+  beforeEach(() => {
+    process.env.SWITCHROOM_PREFIX_WARMUP = '1'
+  })
+
+  it('tags meta.source="warmup"', () => {
+    const { ctx, send } = makeCtx()
+    maybeFireWarmup(ctx)
+    const msg = send.mock.calls[0][0]
+    expect(msg.meta.source).toBe('warmup')
+  })
+
+  it('uses synthetic messageId=0 and userId=0', () => {
+    const { ctx, send } = makeCtx()
+    maybeFireWarmup(ctx)
+    const msg = send.mock.calls[0][0]
+    expect(msg.messageId).toBe(0)
+    expect(msg.userId).toBe(0)
+    expect(msg.user).toBe('switchroom-warmup')
+  })
+
+  it('text carries the NO_REPLY instruction', () => {
+    const { ctx, send } = makeCtx()
+    maybeFireWarmup(ctx)
+    const msg = send.mock.calls[0][0]
+    expect(msg.text).toBe(WARMUP_TEXT)
+    expect(msg.text).toContain('__WARMUP_PING__')
+    expect(msg.text).toContain('NO_REPLY')
+  })
+
+  it('routes to the resolved boot chat', () => {
+    process.env.SWITCHROOM_PREFIX_WARMUP = '1'
+    const { ctx, send } = makeCtx({
+      resolveBootTarget: () => ({ chatId: 'CHAT-9', threadId: 42 }),
+    })
+    maybeFireWarmup(ctx)
+    const msg = send.mock.calls[0][0]
+    expect(msg.chatId).toBe('CHAT-9')
+    expect(msg.threadId).toBe(42)
+  })
+
+  it('omits threadId when boot target has none', () => {
+    const { ctx, send } = makeCtx()
+    maybeFireWarmup(ctx)
+    const msg = send.mock.calls[0][0]
+    expect(msg.threadId).toBeUndefined()
+  })
+})
+
+describe('maybeFireWarmup — cooldown', () => {
+  beforeEach(() => {
+    process.env.SWITCHROOM_PREFIX_WARMUP = '1'
+  })
+
+  it('second call within cooldown is skipped', () => {
+    const { ctx, send, logs } = makeCtx()
+    expect(maybeFireWarmup(ctx)).toBe(true)
+    // Same now() — well within cooldown.
+    expect(maybeFireWarmup(ctx)).toBe(false)
+    expect(send).toHaveBeenCalledTimes(1)
+    expect(logs.some((l) => l.includes('reason=cooldown'))).toBe(true)
+  })
+
+  it('call after cooldown elapses fires again', () => {
+    let t = 1_000_000
+    const ctx = makeCtx({ now: () => t }).ctx
+    expect(maybeFireWarmup(ctx)).toBe(true)
+    t += 5 * 60_000 + 1 // just past cooldown
+    expect(maybeFireWarmup(ctx)).toBe(true)
+  })
+
+  it('cooldown is per-agent', () => {
+    const a = makeCtx({ selfAgent: 'agent-a' })
+    const b = makeCtx({ selfAgent: 'agent-b' })
+    expect(maybeFireWarmup(a.ctx)).toBe(true)
+    expect(maybeFireWarmup(b.ctx)).toBe(true)
+    expect(maybeFireWarmup(a.ctx)).toBe(false) // a in cooldown
+    expect(maybeFireWarmup(b.ctx)).toBe(false) // b in cooldown
+  })
+})
+
+describe('maybeFireWarmup — missing boot target', () => {
+  beforeEach(() => {
+    process.env.SWITCHROOM_PREFIX_WARMUP = '1'
+  })
+
+  it('skipped when no boot chat resolves', () => {
+    const { ctx, send, logs } = makeCtx({ resolveBootTarget: () => null })
+    expect(maybeFireWarmup(ctx)).toBe(false)
+    expect(send).not.toHaveBeenCalled()
+    expect(logs.some((l) => l.includes('reason=no-boot-chat-target'))).toBe(true)
+  })
+})
+
+describe('maybeFireWarmup — send error handling', () => {
+  beforeEach(() => {
+    process.env.SWITCHROOM_PREFIX_WARMUP = '1'
+  })
+
+  it('caught send throw returns false and does not mark cooldown', () => {
+    const send = vi.fn(() => {
+      throw new Error('boom')
+    })
+    const ctx = makeCtx({
+      client: { send } as never,
+    }).ctx
+    expect(maybeFireWarmup(ctx)).toBe(false)
+    // Cooldown NOT recorded — next call should attempt again.
+    expect(maybeFireWarmup(ctx)).toBe(false) // still throws
+    expect(send).toHaveBeenCalledTimes(2)
+  })
+})