switchroom 0.12.27 → 0.12.29

package/dist/cli/switchroom.js

@@ -47247,8 +47247,8 @@ var {
 } = import__.default;
 
 // src/build-info.ts
-var VERSION = "0.12.27";
-var COMMIT_SHA = "64fb245d";
+var VERSION = "0.12.29";
+var COMMIT_SHA = "f7c92422";
 
 // src/cli/agent.ts
 init_source();
@@ -48576,6 +48576,8 @@ function installHindsightPlugin(agentName, agentDir, switchroomConfig) {
     return null;
   const sourcePath = resolveHindsightVendorPath();
   if (!existsSync11(sourcePath)) {
+    process.stderr.write(`installHindsightPlugin: vendor source missing at ${sourcePath} ` + `\u2014 hindsight plugin NOT installed for ${agentName}. ` + `Likely a packaging regression: check the npm tarball's files array.
+`);
     return null;
   }
   const destPath = join8(agentDir, ".claude", "plugins", "hindsight-memory");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.12.27",
+  "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": {
@@ -13,6 +13,7 @@
     "profiles",
     "skills",
     "telegram-plugin",
+    "vendor",
     "bin",
     "README.md",
     "LICENSE"

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

@@ -29800,6 +29800,49 @@ function installPluginLogger(env = process.env) {
   return activeHandle;
 }
 
+// stderr-timestamps.ts
+var installed = false;
+var originalWrite = null;
+var partialBuffer = "";
+function isoTimestamp() {
+  return new Date().toISOString();
+}
+function installStderrTimestamps(env = process.env) {
+  if (env.SWITCHROOM_LOG_TIMESTAMPS === "0")
+    return false;
+  if (installed)
+    return true;
+  const origin = process.stderr.write.bind(process.stderr);
+  originalWrite = origin;
+  const wrapped = function write(chunk, encodingOrCb, cb) {
+    const text = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+    const stamped = stampLines(text);
+    return origin(stamped, encodingOrCb, cb);
+  };
+  process.stderr.write = wrapped;
+  installed = true;
+  return true;
+}
+function stampLines(text, now = isoTimestamp) {
+  if (text === "")
+    return "";
+  let out = "";
+  let i = 0;
+  while (i < text.length) {
+    const nl = text.indexOf(`
+`, i);
+    if (nl === -1) {
+      partialBuffer += text.slice(i);
+      break;
+    }
+    const line = partialBuffer + text.slice(i, nl + 1);
+    partialBuffer = "";
+    out += `[${now()}] ${line}`;
+    i = nl + 1;
+  }
+  return out;
+}
+
 // dm-command-gate.ts
 function decideDmCommandGate(input) {
   if (input.chatType !== "private")
@@ -44160,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();
@@ -47472,10 +47562,10 @@ function sweepStaleTurnActiveMarker(stateDir, opts) {
 }
 
 // ../src/build-info.ts
-var VERSION = "0.12.27";
-var COMMIT_SHA = "64fb245d";
-var COMMIT_DATE = "2026-05-20T07:46:30Z";
-var LATEST_PR = 1588;
+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
@@ -47963,6 +48053,7 @@ function resolveCallingSubagent(opts) {
 
 // gateway/gateway.ts
 var REPLY_TO_TEXT_MAX = 200;
+installStderrTimestamps();
 installPluginLogger();
 installGlobalErrorHandlers();
 process.on("beforeExit", () => {
@@ -48424,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);
@@ -48458,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)
@@ -49383,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

@@ -23,6 +23,7 @@ import { homedir } from 'os'
 import { join, extname, sep, basename } from 'path'
 
 import { installPluginLogger } from '../plugin-logger.js'
+import { installStderrTimestamps } from '../stderr-timestamps.js'
 import { decideDmCommandGate } from '../dm-command-gate.js'
 import { redactAuthCodeMessage } from '../auth-code-redact.js'
 import {
@@ -262,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,
@@ -380,6 +382,10 @@ import { formatIdleFooter } from '../idle-footer.js'
 import { resolveCallingSubagent } from './resolve-calling-subagent.js'
 
 // ─── Stderr logging ───────────────────────────────────────────────────────
+// Install the line-stamper FIRST so it wraps closest to the original
+// stderr.write. plugin-logger's file mirror then sees the timestamped text.
+// Kill switch: SWITCHROOM_LOG_TIMESTAMPS=0 disables.
+installStderrTimestamps()
 installPluginLogger()
 
 // ─── Telemetry ────────────────────────────────────────────────────────────
@@ -1272,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)
@@ -1365,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)
 }
 
 /**
@@ -3262,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/stderr-timestamps.ts

@@ -0,0 +1,106 @@
+/**
+ * Per-line timestamp wrapper for `process.stderr.write`.
+ *
+ * The gateway's stderr is captured to `/var/log/switchroom/gateway-supervisor.log`
+ * by `start.sh`'s `_switchroom_supervise` redirect. The capture has NO
+ * line-level timestamps, which makes it impossible to measure the gap between
+ * events (e.g., `bridge registered` → first `dispatch stage=bridge_recover` →
+ * first `tg-post method=sendMessage`). Without those gaps the cold-start TTFO
+ * RFC's optimization claims (PR #1589) are unverifiable.
+ *
+ * This module installs a one-time wrapper on `process.stderr.write` that
+ * prepends an ISO-8601 timestamp (`[YYYY-MM-DDTHH:MM:SS.mmmZ]`) at the start
+ * of each logical line. Line-buffered: partial writes that don't end in `\n`
+ * are buffered until they do. Newlines mid-chunk split the chunk into
+ * multiple timestamped lines.
+ *
+ * Layered separately from `plugin-logger.ts`'s file mirror so each can be
+ * toggled independently. Order at install time: this wrapper runs FIRST
+ * (closest to the original write), then plugin-logger's file mirror sees
+ * the timestamped text.
+ *
+ * Kill switch: `SWITCHROOM_LOG_TIMESTAMPS=0` disables. Default ON.
+ */
+
+let installed = false
+let originalWrite: typeof process.stderr.write | null = null
+let partialBuffer = ''
+
+function isoTimestamp(): string {
+  return new Date().toISOString()
+}
+
+/**
+ * Wrap `process.stderr.write` to prepend an ISO timestamp at each line
+ * boundary. Idempotent — second call is a no-op.
+ *
+ * Returns true when the wrapper was installed (or was already), false when
+ * the kill-switch env var disabled it.
+ */
+export function installStderrTimestamps(env: NodeJS.ProcessEnv = process.env): boolean {
+  if (env.SWITCHROOM_LOG_TIMESTAMPS === '0') return false
+  if (installed) return true
+
+  const origin = process.stderr.write.bind(process.stderr)
+  originalWrite = origin as typeof process.stderr.write
+
+  const wrapped = function write(
+    chunk: string | Uint8Array,
+    encodingOrCb?: BufferEncoding | ((err?: Error) => void),
+    cb?: (err?: Error) => void,
+  ): boolean {
+    const text = typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8')
+    const stamped = stampLines(text)
+    return (origin as (c: unknown, e?: unknown, cb?: unknown) => boolean)(
+      stamped,
+      encodingOrCb,
+      cb,
+    )
+  } as typeof process.stderr.write
+
+  process.stderr.write = wrapped
+  installed = true
+  return true
+}
+
+/**
+ * Internal: split `text` into lines, prepend `[ISO] ` to each complete
+ * line, leave any trailing partial line buffered for the next call.
+ *
+ * Exported for tests only.
+ */
+export function stampLines(text: string, now: () => string = isoTimestamp): string {
+  if (text === '') return ''
+
+  let out = ''
+  let i = 0
+  while (i < text.length) {
+    const nl = text.indexOf('\n', i)
+    if (nl === -1) {
+      // No more newlines in this chunk — buffer the rest.
+      partialBuffer += text.slice(i)
+      break
+    }
+    // We have a complete line: anything in partialBuffer + slice up to \n.
+    const line = partialBuffer + text.slice(i, nl + 1)
+    partialBuffer = ''
+    out += `[${now()}] ${line}`
+    i = nl + 1
+  }
+  return out
+}
+
+/** Test hook: reset module state. */
+export function __resetForTests(): void {
+  if (installed && originalWrite) {
+    process.stderr.write = originalWrite
+  }
+  installed = false
+  originalWrite = null
+  partialBuffer = ''
+}
+
+/** Test hook: read the current partial buffer (debug-only). */
+export function __getPartialBufferForTests(): string {
+  return partialBuffer
+}