switchroom 0.5.0

package/telegram-plugin/permission-title.ts

@@ -0,0 +1,117 @@
+/**
+ * Build a human-readable title for the inline-keyboard permission
+ * approval message. Pre-fix the title was always `🔐 Permission:
+ * ${toolName}` — for a `Skill` or `Bash` call the user couldn't tell
+ * which skill / command was being approved without tapping "See more".
+ *
+ * The detail surfaces (the expanded view at server.ts/gateway.ts) still
+ * render the full description + input_preview block; this helper just
+ * lifts the most identifying field into the title so the user can
+ * approve at a glance.
+ *
+ * See #186.
+ */
+
+import { basename } from "node:path";
+
+const COMMAND_TITLE_MAX = 40;
+const PATH_TITLE_MAX = 40;
+
+/**
+ * Build a title fragment for a permission prompt. Returns the toolName
+ * for any tool we don't recognise — the helper is intentionally
+ * conservative: better to keep the bare name than render gibberish from
+ * a malformed input_preview.
+ */
+export function summarizeToolForTitle(
+  toolName: string,
+  inputPreview: string | undefined,
+): string {
+  const input = parseInput(inputPreview);
+  if (!input) return toolName;
+
+  switch (toolName) {
+    case "Skill": {
+      // Claude Code's Skill tool input shape has shifted across versions
+      // and skill flavours. Read defensively from every known field
+      // before falling back to the bare tool name — the user reported
+      // a popup that rendered as `🔐 Permission: Skill` (no brackets)
+      // because we'd only checked `skill`. The skill name is the most
+      // identifying field of the prompt; never drop it silently.
+      const skill =
+        readString(input, "skill") ??
+        readString(input, "skill_name") ??
+        readString(input, "skillName") ??
+        readString(input, "name") ??
+        skillBasenameFromPath(input);
+      return skill ? `${toolName} (${skill})` : toolName;
+    }
+    case "Bash": {
+      const command = readString(input, "command");
+      return command ? `${toolName}: ${truncate(command, COMMAND_TITLE_MAX)}` : toolName;
+    }
+    case "Read":
+    case "Edit":
+    case "Write":
+    case "MultiEdit":
+    case "NotebookEdit": {
+      const filePath = readString(input, "file_path") ?? readString(input, "notebook_path");
+      return filePath ? `${toolName}: ${truncate(basename(filePath), PATH_TITLE_MAX)}` : toolName;
+    }
+    case "Glob":
+    case "Grep": {
+      const pattern = readString(input, "pattern");
+      return pattern ? `${toolName}: ${truncate(pattern, COMMAND_TITLE_MAX)}` : toolName;
+    }
+    case "WebFetch":
+    case "WebSearch": {
+      const query = readString(input, "url") ?? readString(input, "query");
+      return query ? `${toolName}: ${truncate(query, COMMAND_TITLE_MAX)}` : toolName;
+    }
+    default:
+      return toolName;
+  }
+}
+
+function parseInput(raw: string | undefined): Record<string, unknown> | null {
+  if (!raw || typeof raw !== "string") return null;
+  const trimmed = raw.trim();
+  if (!trimmed.startsWith("{")) return null;
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed as Record<string, unknown>;
+    }
+  } catch {
+    /* fall through */
+  }
+  return null;
+}
+
+function readString(input: Record<string, unknown>, key: string): string | null {
+  const value = input[key];
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+/**
+ * Some Skill tool variants pass the skill as a directory path (e.g.
+ * `skills/mail/SKILL.md` or `~/.switchroom/skills/mail`). Lift the
+ * skill name out of the path so the popup still says `Skill (mail)`
+ * instead of dumping the full path or bare `Skill`.
+ */
+function skillBasenameFromPath(input: Record<string, unknown>): string | null {
+  const path = readString(input, "path") ?? readString(input, "skill_path");
+  if (!path) return null;
+  // Strip a trailing /SKILL.md or filename so we land on the directory
+  // basename — that's the canonical skill name in switchroom's layout.
+  const trimmed = path.replace(/\/SKILL\.md$/i, "").replace(/\/$/, "");
+  const lastSlash = trimmed.lastIndexOf("/");
+  const basename = lastSlash >= 0 ? trimmed.slice(lastSlash + 1) : trimmed;
+  return basename.length > 0 ? basename : null;
+}
+
+function truncate(text: string, max: number): string {
+  const collapsed = text.replace(/\s+/g, " ").trim();
+  if (collapsed.length <= max) return collapsed;
+  return collapsed.slice(0, max - 1) + "…";
+}

package/telegram-plugin/pin-event-log.ts

@@ -0,0 +1,76 @@
+/**
+ * Structured logger for pin/unpin lifecycle events.
+ *
+ * Every call to `pinChatMessage` or `unpinChatMessage` — whether from the
+ * live turn path or the crash/restart sweeps — emits one JSON-encoded line
+ * on stderr, prefixed with `pin-event:`. This gives an out-of-band audit
+ * trail operators can grep without parsing free-form log text.
+ *
+ * Pure helper. No globals. The write target is injectable for tests.
+ */
+
+export type PinEventName =
+  | 'pin'
+  | 'unpin'
+  | 'unpin-retry'
+  | 'sweep-pin'
+  | 'sweep-auth'
+  | 'audit-orphan'
+
+export type PinEventOutcome =
+  | 'ok'
+  | 'fail'
+  | 'rate-limited'
+  | 'forbidden'
+  | 'timeout'
+  | 'observed'
+
+export interface PinEvent {
+  event: PinEventName
+  chatId: string
+  messageId?: number
+  turnKey?: string
+  outcome: PinEventOutcome
+  error?: string
+  durationMs?: number
+}
+
+export type PinEventWriter = (line: string) => void
+
+const defaultWriter: PinEventWriter = (line) => {
+  process.stderr.write(line)
+}
+
+export function logPinEvent(event: PinEvent, write: PinEventWriter = defaultWriter): void {
+  const payload = JSON.stringify(event)
+  write(`pin-event: ${payload}\n`)
+}
+
+/**
+ * Classify a thrown Error from the Telegram API into a stable outcome
+ * category. Grammy surfaces rate-limit errors with `error_code: 429` and
+ * permission errors with `error_code: 403`; everything else is generic
+ * failure. We match on the message body as a last resort for the error
+ * shapes that don't surface `error_code` (network timeouts, HTTP-level
+ * 429s in the wrapper, etc.) so the category is useful even when the
+ * Grammy wrapper hides the structured field.
+ */
+export function classifyPinError(err: unknown): PinEventOutcome {
+  if (err == null) return 'fail'
+  const anyErr = err as { error_code?: number; description?: string; message?: string }
+  const code = anyErr.error_code
+  if (code === 429) return 'rate-limited'
+  if (code === 403) return 'forbidden'
+  const msg = (anyErr.description ?? anyErr.message ?? String(err)).toLowerCase()
+  if (msg.includes('too many requests') || msg.includes('rate')) return 'rate-limited'
+  if (msg.includes('forbidden') || msg.includes('not enough rights')) return 'forbidden'
+  if (msg.includes('timeout') || msg.includes('etimedout')) return 'timeout'
+  return 'fail'
+}
+
+export function errorMessage(err: unknown): string {
+  if (err == null) return ''
+  if (err instanceof Error) return err.message
+  const anyErr = err as { description?: string; message?: string }
+  return anyErr.description ?? anyErr.message ?? String(err)
+}

package/telegram-plugin/plugin-logger.ts

@@ -0,0 +1,136 @@
+/**
+ * Centralized stderr logger for the telegram plugin.
+ *
+ * Background: every `process.stderr.write(...)` call in server.ts goes to
+ * the bun subprocess's stderr, which Claude Code does NOT forward anywhere.
+ * That makes the plugin effectively blind in production. This module
+ * installs a one-time redirect at startup so every stderr write is ALSO
+ * appended to a logfile at `~/.switchroom/logs/telegram-plugin.log` (override
+ * via `SWITCHROOM_TELEGRAM_LOG_PATH`), with simple size-based rotation.
+ *
+ * Design choices:
+ * - Wrap `process.stderr.write` rather than editing every callsite. The
+ *   original stderr is preserved (still flows to bun), the file sink is
+ *   additional.
+ * - Synchronous `fs.appendFileSync` / `fs.renameSync`: stderr.write is
+ *   already sync-ish in the rest of the codebase and we want the log
+ *   line to survive a crash happening on the next tick.
+ * - Rotation is cheap (rename current → `.1`) and capped at a single
+ *   backup. Logs are debug-grade; no one needs a week of history.
+ */
+
+import { appendFileSync, mkdirSync, renameSync, statSync, existsSync } from 'fs'
+import { homedir } from 'os'
+import { dirname, join } from 'path'
+
+const DEFAULT_LOG_PATH = join(homedir(), '.switchroom', 'logs', 'telegram-plugin.log')
+const ROTATE_AT_BYTES = 5 * 1024 * 1024 // 5 MB
+
+export interface PluginLoggerHandle {
+  /** Stop intercepting and restore the original stderr.write. */
+  uninstall(): void
+  /** The resolved logfile path (after env override + dir creation). */
+  readonly logPath: string
+}
+
+let activeHandle: PluginLoggerHandle | null = null
+
+/**
+ * Resolve the effective logfile path. Env override wins; otherwise the
+ * default under the user's home dir. Exposed so tests can assert the
+ * resolution logic without actually installing the interceptor.
+ */
+export function resolveLogPath(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env.SWITCHROOM_TELEGRAM_LOG_PATH
+  if (override && override.length > 0) return override
+  return DEFAULT_LOG_PATH
+}
+
+function ensureDir(path: string): void {
+  try {
+    mkdirSync(dirname(path), { recursive: true })
+  } catch {
+    // If we can't create the dir, the appendFileSync call will fail and
+    // we'll swallow — the original stderr still flows regardless.
+  }
+}
+
+function rotateIfNeeded(path: string): void {
+  try {
+    const st = statSync(path)
+    if (st.size < ROTATE_AT_BYTES) return
+    const backup = `${path}.1`
+    renameSync(path, backup)
+  } catch {
+    // File doesn't exist yet, or rotation failed — either way, keep going.
+  }
+}
+
+/**
+ * Install the stderr interceptor. Idempotent: a second call returns the
+ * existing handle. Returns a handle with an `uninstall()` method primarily
+ * for tests (production installs once at server bootstrap).
+ */
+export function installPluginLogger(env: NodeJS.ProcessEnv = process.env): PluginLoggerHandle {
+  if (activeHandle != null) return activeHandle
+
+  const logPath = resolveLogPath(env)
+  ensureDir(logPath)
+
+  const originalWrite = process.stderr.write.bind(process.stderr)
+
+  const wrapped = function write(
+    chunk: string | Uint8Array,
+    encodingOrCb?: BufferEncoding | ((err?: Error) => void),
+    cb?: (err?: Error) => void,
+  ): boolean {
+    // Forward to original stderr first so behavior is unchanged for anyone
+    // reading stderr directly.
+    const ok = (originalWrite as (c: unknown, e?: unknown, cb?: unknown) => boolean)(
+      chunk,
+      encodingOrCb,
+      cb,
+    )
+
+    // Also append to the logfile. Best-effort: never throw from stderr.write.
+    try {
+      const text = typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8')
+      rotateIfNeeded(logPath)
+      appendFileSync(logPath, text)
+    } catch {
+      // Swallow — we never want the logger to break the host.
+    }
+
+    return ok
+  } as typeof process.stderr.write
+
+  process.stderr.write = wrapped
+
+  activeHandle = {
+    logPath,
+    uninstall(): void {
+      if (activeHandle == null) return
+      process.stderr.write = originalWrite
+      activeHandle = null
+    },
+  }
+  return activeHandle
+}
+
+/** Exposed for tests that need to reset module-level state. */
+export function _resetForTests(): void {
+  if (activeHandle != null) {
+    try {
+      activeHandle.uninstall()
+    } catch {
+      // ignore
+    }
+  }
+  activeHandle = null
+}
+
+/** Constants exported for tests. */
+export const _internals = {
+  DEFAULT_LOG_PATH,
+  ROTATE_AT_BYTES,
+}