switchroom 0.5.0

package/telegram-plugin/operator-events.ts

@@ -0,0 +1,421 @@
+/**
+ * operator-events.ts — taxonomy + classifier + renderer for runtime errors
+ * bubbled to the operator via Telegram.
+ *
+ * Design goals:
+ *  - Pure module: zero grammy/gateway deps (types are inlined or imported
+ *    from grammy's type-only surface).
+ *  - classifyClaudeError MUST NOT throw on unfamiliar shapes — always falls
+ *    through to unknown-4xx / unknown-5xx rather than swallowing silently.
+ *  - Per-agent per-kind cooldown (default 5 min) deduplicates storms.
+ *  - renderOperatorEvent owns ALL user-facing HTML for each kind,
+ *    including the quota-exhausted strings migrated from auto-fallback.ts.
+ */
+
+// ─── Taxonomy ────────────────────────────────────────────────────────────────
+
+export type OperatorEventKind =
+  | 'credentials-expired'
+  | 'credentials-invalid'
+  | 'credit-exhausted'
+  | 'quota-exhausted'
+  | 'rate-limited'
+  | 'agent-crashed'
+  | 'agent-restarted-unexpectedly'
+  | 'unknown-4xx'
+  | 'unknown-5xx'
+
+export interface OperatorEvent {
+  kind: OperatorEventKind
+  agent: string
+  detail: string
+  suggestedActions: string[]
+  firstSeenAt: Date
+}
+
+// ─── Inline keyboard type (mirrors grammy's InlineKeyboardMarkup) ─────────────
+
+export interface InlineKeyboardButton {
+  text: string
+  callback_data?: string
+  url?: string
+}
+
+export interface InlineKeyboardMarkup {
+  inline_keyboard: InlineKeyboardButton[][]
+}
+
+// ─── Classifier ───────────────────────────────────────────────────────────────
+
+/**
+ * Classify an error value from any source (Anthropic SDK throw, JSONL error
+ * field, etc.) into an OperatorEventKind.
+ *
+ * CONTRACT: never throws. Unfamiliar shapes fall through to unknown-4xx or
+ * unknown-5xx based on HTTP status, defaulting to unknown-4xx.
+ */
+export function classifyClaudeError(raw: unknown): OperatorEventKind {
+  try {
+    return classifyInner(raw)
+  } catch {
+    return 'unknown-4xx'
+  }
+}
+
+function classifyInner(raw: unknown): OperatorEventKind {
+  if (raw == null) return 'unknown-4xx'
+
+  // Extract common fields defensively — never throw on bad shapes.
+  const obj = typeof raw === 'object' ? (raw as Record<string, unknown>) : {}
+  const errorType = extractString(obj, 'error_type') ??
+    extractString(obj, 'type') ??
+    extractString(getNestedObj(obj, 'error'), 'type') ??
+    ''
+  const errorCode = extractString(obj, 'code') ??
+    extractString(getNestedObj(obj, 'error'), 'code') ??
+    ''
+  const message = extractString(obj, 'message') ??
+    extractString(getNestedObj(obj, 'error'), 'message') ??
+    (typeof raw === 'string' ? raw : '') ??
+    ''
+  const status = extractNumber(obj, 'status') ??
+    extractNumber(obj, 'statusCode') ??
+    extractNumber(obj, 'status_code') ??
+    null
+
+  // Anthropic SDK: error_code field (newer SDK shape)
+  const sdkCode = extractString(obj, 'error_code') ?? ''
+
+  // Map known Anthropic error types/codes first.
+  // Source: https://docs.anthropic.com/en/api/errors
+  if (
+    errorType === 'authentication_error' ||
+    errorCode === 'authentication_error' ||
+    sdkCode === 'authentication_error' ||
+    message.toLowerCase().includes('authentication_error')
+  ) {
+    // Distinguish expired vs invalid by message hints.
+    const msg = message.toLowerCase()
+    if (msg.includes('expired') || msg.includes('refresh')) {
+      return 'credentials-expired'
+    }
+    return 'credentials-invalid'
+  }
+
+  if (
+    errorType === 'invalid_api_key' ||
+    errorCode === 'invalid_api_key' ||
+    sdkCode === 'invalid_api_key' ||
+    message.toLowerCase().includes('invalid_api_key') ||
+    message.toLowerCase().includes('invalid api key')
+  ) {
+    return 'credentials-invalid'
+  }
+
+  if (
+    errorType === 'credit_balance_too_low' ||
+    errorCode === 'credit_balance_too_low' ||
+    sdkCode === 'credit_balance_too_low' ||
+    message.toLowerCase().includes('credit_balance_too_low') ||
+    message.toLowerCase().includes('credit balance')
+  ) {
+    return 'credit-exhausted'
+  }
+
+  if (
+    errorType === 'rate_limit_error' ||
+    errorCode === 'rate_limit_error' ||
+    sdkCode === 'rate_limit_error' ||
+    message.toLowerCase().includes('rate_limit_error') ||
+    message.toLowerCase().includes('rate limit')
+  ) {
+    return 'rate-limited'
+  }
+
+  if (
+    errorType === 'overloaded_error' ||
+    errorCode === 'overloaded_error' ||
+    sdkCode === 'overloaded_error' ||
+    message.toLowerCase().includes('overloaded_error') ||
+    message.toLowerCase().includes('overloaded')
+  ) {
+    // Anthropic overloaded = quota exhausted / service rate-limiting
+    return 'quota-exhausted'
+  }
+
+  // Synthetic kinds (non-Anthropic — set by session-tail or IPC bridge)
+  if (errorType === 'agent-crashed' || errorCode === 'agent-crashed') {
+    return 'agent-crashed'
+  }
+  if (
+    errorType === 'agent-restarted-unexpectedly' ||
+    errorCode === 'agent-restarted-unexpectedly'
+  ) {
+    return 'agent-restarted-unexpectedly'
+  }
+
+  // Fallback: HTTP status-based.
+  if (status != null) {
+    if (status >= 400 && status < 500) return 'unknown-4xx'
+    if (status >= 500 && status < 600) return 'unknown-5xx'
+  }
+
+  return 'unknown-4xx'
+}
+
+function extractString(obj: Record<string, unknown>, key: string): string | null {
+  const v = obj[key]
+  return typeof v === 'string' && v.length > 0 ? v : null
+}
+
+function extractNumber(obj: Record<string, unknown>, key: string): number | null {
+  const v = obj[key]
+  return typeof v === 'number' ? v : null
+}
+
+function getNestedObj(obj: Record<string, unknown>, key: string): Record<string, unknown> {
+  const v = obj[key]
+  return typeof v === 'object' && v != null ? (v as Record<string, unknown>) : {}
+}
+
+// ─── Renderer ─────────────────────────────────────────────────────────────────
+
+export interface RenderResult {
+  text: string
+  keyboard: InlineKeyboardMarkup
+}
+
+/**
+ * Render an OperatorEvent into Telegram HTML + inline keyboard.
+ *
+ * For quota-exhausted: this is the canonical source of the user-facing
+ * message text, superseding the strings that were previously in
+ * auto-fallback.ts. The decision logic (slot switching, mark-exhausted)
+ * stays in auto-fallback.ts; only the rendered text lives here.
+ *
+ * callback_data encoding: agent names are URL-encoded in all callback_data
+ * strings (e.g. `op:reauth:<encoded-agent>`). The Phase 4b callback_query
+ * handler MUST decodeURIComponent() the third segment when parsing. This is
+ * defense-in-depth alongside the slug validation in createAgent — together
+ * they ensure neither side can fail independently even if names ever contain
+ * `:` or other delimiter characters.
+ */
+export function renderOperatorEvent(ev: OperatorEvent): RenderResult {
+  const agent = escHtml(ev.agent)
+  const detail = escHtml(ev.detail)
+
+  switch (ev.kind) {
+    case 'credentials-expired':
+      return {
+        text: [
+          `🔑 <b>Claude login expired</b> for <b>${agent}</b>.`,
+          detail ? `<i>${detail}</i>` : '',
+          `Tap <b>Reauth now</b> to refresh credentials.`,
+        ]
+          .filter(Boolean)
+          .join('\n'),
+        keyboard: {
+          inline_keyboard: [
+            [
+              { text: '🔐 Reauth now', callback_data: `op:reauth:${encodeURIComponent(ev.agent)}` },
+              { text: '❌ Dismiss', callback_data: `op:dismiss:${encodeURIComponent(ev.agent)}` },
+            ],
+          ],
+        },
+      }
+
+    case 'credentials-invalid':
+      return {
+        text: [
+          `🔑 <b>Invalid Claude credentials</b> for <b>${agent}</b>.`,
+          detail ? `<i>${detail}</i>` : '',
+          `Run <code>/auth reauth ${agent}</code> or tap below.`,
+        ]
+          .filter(Boolean)
+          .join('\n'),
+        keyboard: {
+          inline_keyboard: [
+            [
+              { text: '🔐 Reauth now', callback_data: `op:reauth:${encodeURIComponent(ev.agent)}` },
+              { text: '❌ Dismiss', callback_data: `op:dismiss:${encodeURIComponent(ev.agent)}` },
+            ],
+          ],
+        },
+      }
+
+    case 'credit-exhausted':
+      return {
+        text: [
+          `💳 <b>Credit balance too low</b> for <b>${agent}</b>.`,
+          detail ? `<i>${detail}</i>` : '',
+          `Swap to another account slot or add a new one.`,
+        ]
+          .filter(Boolean)
+          .join('\n'),
+        keyboard: {
+          inline_keyboard: [
+            [
+              { text: '🔄 Swap slot', callback_data: `op:swap-slot:${encodeURIComponent(ev.agent)}` },
+              { text: '➕ Add slot', callback_data: `op:add-slot:${encodeURIComponent(ev.agent)}` },
+            ],
+            [{ text: '⏳ Wait', callback_data: `op:dismiss:${encodeURIComponent(ev.agent)}` }],
+          ],
+        },
+      }
+
+    case 'quota-exhausted':
+      // Canonical quota-exhausted text (migrated from auto-fallback.ts).
+      // auto-fallback.ts's buildSwitchedMessage / buildAllExhaustedMessage
+      // are the historical source; this is now the single owner.
+      return {
+        text: [
+          `⚠️ <b>Quota exhausted</b> for <b>${agent}</b>.`,
+          detail ? `<i>${detail}</i>` : '',
+          `All account slots are at the usage limit. Switchroom will auto-fallback when another slot is available.`,
+        ]
+          .filter(Boolean)
+          .join('\n'),
+        keyboard: {
+          inline_keyboard: [
+            [
+              { text: '🔄 Swap slot', callback_data: `op:swap-slot:${encodeURIComponent(ev.agent)}` },
+              { text: '➕ Add slot', callback_data: `op:add-slot:${encodeURIComponent(ev.agent)}` },
+            ],
+            [{ text: '⏳ Wait', callback_data: `op:dismiss:${encodeURIComponent(ev.agent)}` }],
+          ],
+        },
+      }
+
+    case 'rate-limited':
+      return {
+        text: [
+          `🚦 <b>Rate limited</b> for <b>${agent}</b>.`,
+          detail ? `<i>${detail}</i>` : '',
+          `Claude is temporarily rate-limiting requests. Will retry automatically.`,
+        ]
+          .filter(Boolean)
+          .join('\n'),
+        keyboard: {
+          inline_keyboard: [
+            [{ text: '⏳ Wait', callback_data: `op:dismiss:${encodeURIComponent(ev.agent)}` }],
+          ],
+        },
+      }
+
+    case 'agent-crashed':
+      return {
+        text: [
+          `💥 <b>Agent crashed</b>: <b>${agent}</b>.`,
+          detail ? `<i>${detail}</i>` : '',
+        ]
+          .filter(Boolean)
+          .join('\n'),
+        keyboard: {
+          inline_keyboard: [
+            [
+              { text: '🔄 Restart', callback_data: `op:restart:${encodeURIComponent(ev.agent)}` },
+              { text: '📋 Show logs', callback_data: `op:logs:${encodeURIComponent(ev.agent)}` },
+            ],
+          ],
+        },
+      }
+
+    case 'agent-restarted-unexpectedly':
+      return {
+        text: [
+          `🔄 <b>Agent restarted unexpectedly</b>: <b>${agent}</b>.`,
+          detail ? `<i>${detail}</i>` : '',
+          `This may indicate a crash-loop. Check logs if it happens again.`,
+        ]
+          .filter(Boolean)
+          .join('\n'),
+        keyboard: {
+          inline_keyboard: [
+            [
+              { text: '📋 Show logs', callback_data: `op:logs:${encodeURIComponent(ev.agent)}` },
+              { text: '❌ Dismiss', callback_data: `op:dismiss:${encodeURIComponent(ev.agent)}` },
+            ],
+          ],
+        },
+      }
+
+    case 'unknown-4xx':
+      return {
+        text: [
+          `⚠️ <b>API error (4xx)</b> for <b>${agent}</b>.`,
+          detail ? `<code>${detail}</code>` : '',
+        ]
+          .filter(Boolean)
+          .join('\n'),
+        keyboard: {
+          inline_keyboard: [
+            [
+              { text: '🔐 Reauth', callback_data: `op:reauth:${encodeURIComponent(ev.agent)}` },
+              { text: '❌ Dismiss', callback_data: `op:dismiss:${encodeURIComponent(ev.agent)}` },
+            ],
+          ],
+        },
+      }
+
+    case 'unknown-5xx':
+      return {
+        text: [
+          `🔥 <b>Server error (5xx)</b> for <b>${agent}</b>.`,
+          detail ? `<code>${detail}</code>` : '',
+          `Anthropic may be experiencing issues. Will retry automatically.`,
+        ]
+          .filter(Boolean)
+          .join('\n'),
+        keyboard: {
+          inline_keyboard: [
+            [{ text: '⏳ Wait', callback_data: `op:dismiss:${encodeURIComponent(ev.agent)}` }],
+          ],
+        },
+      }
+  }
+}
+
+// ─── Per-agent per-kind cooldown ─────────────────────────────────────────────
+
+export const DEFAULT_OPERATOR_EVENT_COOLDOWN_MS = 5 * 60_000 // 5 minutes
+
+/**
+ * In-memory cooldown tracker. Keyed by `${agent}:${kind}`.
+ * Prevents repeated notifications for the same transient error storm.
+ */
+const cooldownMap = new Map<string, number>()
+
+export function shouldEmitOperatorEvent(
+  agent: string,
+  kind: OperatorEventKind,
+  now: number = Date.now(),
+  cooldownMs: number = DEFAULT_OPERATOR_EVENT_COOLDOWN_MS,
+): boolean {
+  const key = `${agent}:${kind}`
+  const last = cooldownMap.get(key)
+  if (last != null && now - last < cooldownMs) {
+    return false
+  }
+  cooldownMap.set(key, now)
+  return true
+}
+
+/** Clear cooldown for a specific agent+kind (e.g. after reauth succeeds). */
+export function clearOperatorEventCooldown(agent: string, kind: OperatorEventKind): void {
+  cooldownMap.delete(`${agent}:${kind}`)
+}
+
+/** Reset ALL cooldowns (for testing). */
+export function resetAllCooldowns(): void {
+  cooldownMap.clear()
+}
+
+// ─── HTML escape ─────────────────────────────────────────────────────────────
+
+function escHtml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}

package/telegram-plugin/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@switchroom-ai/telegram-plugin",
+  "version": "0.1.0",
+  "description": "Telegram MCP plugin for Switchroom — forum topic routing, status reactions, SQLite history.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "switchroom-telegram-plugin": "./dist/server.js",
+    "switchroom-telegram-gateway": "./dist/gateway/gateway.js"
+  },
+  "main": "./dist/server.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "bun start.js",
+    "start:source": "bun server.ts",
+    "start:dist": "bun dist/server.js",
+    "build": "node scripts/build.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@grammyjs/runner": "^2.0.3",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@secretlint/core": "^12.2.0",
+    "@secretlint/secretlint-rule-preset-recommend": "^12.2.0",
+    "@secretlint/types": "^12.2.0",
+    "@xterm/headless": "^6.0.0",
+    "grammy": "^1.21.0"
+  },
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mekenthompson/switchroom.git",
+    "directory": "telegram-plugin"
+  },
+  "homepage": "https://github.com/mekenthompson/switchroom/tree/main/telegram-plugin#readme",
+  "bugs": {
+    "url": "https://github.com/mekenthompson/switchroom/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "switchroom",
+    "claude-code",
+    "telegram",
+    "mcp",
+    "model-context-protocol"
+  ]
+}

package/telegram-plugin/permission-rule.ts

@@ -0,0 +1,133 @@
+/**
+ * Resolve a Claude Code permission allow-rule from a permission_request
+ * payload — the value we'd add to `tools.allow` in switchroom.yaml so
+ * future invocations of the same operation never pop another approval
+ * dialog.
+ *
+ * Used by the Telegram permission popup's "🔁 Always allow" button
+ * (issue follow-up to #186). Per-skill granularity for `Skill` so
+ * tapping "Always" on a `Skill (mail)` prompt only whitelists `mail`,
+ * not all skills. Other tools fall back to the bare tool name —
+ * promoting `Bash` from per-call confirm to always-allow is a more
+ * meaningful blast-radius decision and shouldn't be hidden behind a
+ * one-tap button on an arbitrary command, but the bare-name behaviour
+ * is consistent with how the existing `tools.allow: [Bash]` works.
+ *
+ * Returns:
+ *   - `{ rule, label }` when we can compute a rule for the agent's yaml
+ *   - `null` when the tool is something we don't know how to allow at
+ *     a meaningful granularity (caller should disable the Always button
+ *     to avoid writing a useless or dangerously-broad rule)
+ *
+ * The `label` is what we surface to the operator in the confirmation
+ * — "🔁 Always allow Skill(mail) for clerk". The rule is what lands in
+ * yaml: matches Claude Code's settings.json permission-rule grammar
+ * (`Tool` or `Tool(arg)` for granular).
+ */
+
+import { basename } from "node:path";
+
+export interface AlwaysAllowRule {
+  /** The exact string to add to `tools.allow` in switchroom.yaml. */
+  readonly rule: string;
+  /** Human-readable label for the confirmation message. */
+  readonly label: string;
+}
+
+/**
+ * @param toolName    Claude Code's tool_name from the permission_request
+ * @param inputPreview JSON string with the tool's input. May be undefined
+ *                     or non-JSON; the function is conservative.
+ */
+export function resolveAlwaysAllowRule(
+  toolName: string,
+  inputPreview: string | undefined,
+): AlwaysAllowRule | null {
+  if (!toolName) return null;
+  const input = parseInput(inputPreview);
+
+  switch (toolName) {
+    case "Skill": {
+      // Per-skill granularity: `Skill(mail)`. Mirror permission-title's
+      // defensive field-fallback so the rule resolves whenever the
+      // popup managed to render the skill name in brackets.
+      if (!input) return null;
+      const skill =
+        readString(input, "skill") ??
+        readString(input, "skill_name") ??
+        readString(input, "skillName") ??
+        readString(input, "name") ??
+        skillBasenameFromPath(input);
+      if (!skill) return null;
+      // Claude Code's permission-rule grammar quotes the arg with
+      // parentheses, no inner quoting needed for typical skill names
+      // (alphanumeric + dash/underscore/dot). Refuse rules with
+      // characters that could break the parser or expand to unintended
+      // matches.
+      if (!/^[A-Za-z0-9._\-+]+$/.test(skill)) return null;
+      return {
+        rule: `Skill(${skill})`,
+        label: `Skill(${skill})`,
+      };
+    }
+    case "Bash":
+    case "Read":
+    case "Write":
+    case "Edit":
+    case "MultiEdit":
+    case "NotebookEdit":
+    case "Glob":
+    case "Grep":
+    case "WebFetch":
+    case "WebSearch":
+    case "Task":
+    case "Agent":
+    case "TodoWrite":
+    case "ExitPlanMode": {
+      // Bare tool name — same shape as `tools.allow: [Bash]`. We
+      // don't pattern-match the args here: that's the operator's job
+      // when they want fine control. The Telegram button is for the
+      // common "I trust this skill / this tool category" case, not
+      // for synthesizing precise Bash glob rules.
+      return { rule: toolName, label: toolName };
+    }
+    default: {
+      // MCP tools (mcp__server__tool) come through with their full
+      // namespaced name. Pre-approve the exact tool — same pattern
+      // the scaffold already uses for SWITCHROOM_TELEGRAM_MCP_TOOLS.
+      if (/^mcp__[A-Za-z0-9_\-]+(__[A-Za-z0-9_\-]+)?$/.test(toolName)) {
+        return { rule: toolName, label: toolName };
+      }
+      // Unknown tool — refuse rather than write a rule we can't
+      // explain. Leaves the operator to add it via the CLI.
+      return null;
+    }
+  }
+}
+
+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;
+}
+
+function skillBasenameFromPath(input: Record<string, unknown>): string | null {
+  const path = readString(input, "path") ?? readString(input, "skill_path");
+  if (!path) return null;
+  const trimmed = path.replace(/\/SKILL\.md$/i, "").replace(/\/$/, "");
+  return basename(trimmed) || null;
+}