switchroom 0.7.15 → 0.10.0

package/telegram-plugin/analytics-posthog.ts

@@ -0,0 +1,191 @@
+/**
+ * analytics-posthog.ts — gateway-side PostHog client.
+ *
+ * Mirrors `src/analytics/posthog.ts` (the CLI's client) but sized for a
+ * long-lived gateway process: default batching instead of immediate-flush.
+ * Honours the same env vars (SWITCHROOM_POSTHOG_KEY, SWITCHROOM_POSTHOG_HOST,
+ * SWITCHROOM_TELEMETRY_DISABLED) so an operator opt-out applies fleet-wide.
+ *
+ * Distinct ID lineage:
+ *   1. SWITCHROOM_ANALYTICS_ID env var — set by compose.ts from the host's
+ *      ~/.switchroom/analytics-id so per-agent runtime events merge with
+ *      the same user's CLI events in PostHog.
+ *   2. Per-agent fallback UUID at /state/agent/analytics-id when the env
+ *      var is missing (e.g. legacy compose). Persists across restarts.
+ *
+ * Every event auto-stamps `agent` and `switchroom_version` so dashboards
+ * can slice by agent without each call-site repeating the property.
+ */
+
+import { PostHog } from 'posthog-node'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { randomUUID } from 'node:crypto'
+
+const DEFAULT_KEY = 'phc_qKY87cKWZm6ZyCtk7LcRd2cU8Sg42u7Ywhui5stYCegd'
+const DEFAULT_HOST = 'https://us.i.posthog.com'
+
+let client: PostHog | null = null
+let initialized = false
+let cachedDistinctId: string | null = null
+let globalHandlersInstalled = false
+
+function telemetryDisabled(): boolean {
+  const v = process.env.SWITCHROOM_TELEMETRY_DISABLED
+  return v === '1' || v === 'true'
+}
+
+function agentName(): string {
+  return process.env.SWITCHROOM_AGENT_NAME ?? 'unknown'
+}
+
+function switchroomVersion(): string {
+  return process.env.SWITCHROOM_VERSION ?? 'unknown'
+}
+
+export function getDistinctId(): string {
+  if (cachedDistinctId) return cachedDistinctId
+  const envId = process.env.SWITCHROOM_ANALYTICS_ID
+  if (envId && envId.trim() !== '') {
+    cachedDistinctId = envId.trim()
+    return cachedDistinctId
+  }
+  const fallbackPath = join(
+    process.env.SWITCHROOM_RUNTIME_STATE_DIR ?? '/state/agent',
+    'analytics-id',
+  )
+  try {
+    if (existsSync(fallbackPath)) {
+      const existing = readFileSync(fallbackPath, 'utf-8').trim()
+      if (existing) {
+        cachedDistinctId = existing
+        return existing
+      }
+    }
+  } catch {
+    // fall through to fresh uuid
+  }
+  const id = randomUUID()
+  cachedDistinctId = id
+  try {
+    mkdirSync(dirname(fallbackPath), { recursive: true })
+    writeFileSync(fallbackPath, id, 'utf-8')
+  } catch {
+    // non-fatal — fresh uuid next boot is acceptable
+  }
+  return id
+}
+
+export function getPostHog(): PostHog | null {
+  if (initialized) return client
+  initialized = true
+  if (telemetryDisabled()) return null
+  const apiKey = process.env.SWITCHROOM_POSTHOG_KEY ?? DEFAULT_KEY
+  const host = process.env.SWITCHROOM_POSTHOG_HOST ?? DEFAULT_HOST
+  if (!apiKey) return null
+  try {
+    client = new PostHog(apiKey, {
+      host,
+      // Long-lived gateway: rely on default batching instead of the
+      // immediate-flush the short-lived CLI uses.
+      enableExceptionAutocapture: false,
+      // IP is considered PII in our telemetry policy (see docs/posthog.md).
+      disableGeoip: true,
+    })
+  } catch {
+    client = null
+  }
+  return client
+}
+
+export async function captureEvent(
+  event: string,
+  properties: Record<string, unknown> = {},
+): Promise<void> {
+  const ph = getPostHog()
+  if (!ph) return
+  try {
+    ph.capture({
+      distinctId: getDistinctId(),
+      event,
+      properties: {
+        agent: agentName(),
+        switchroom_version: switchroomVersion(),
+        source: 'gateway',
+        ...properties,
+      },
+    })
+  } catch {
+    // Telemetry must never break the gateway.
+  }
+}
+
+export async function captureException(
+  error: unknown,
+  properties: Record<string, unknown> = {},
+): Promise<void> {
+  const ph = getPostHog()
+  if (!ph) return
+  try {
+    await ph.captureException(error, getDistinctId(), {
+      agent: agentName(),
+      switchroom_version: switchroomVersion(),
+      source: 'gateway',
+      ...properties,
+    })
+  } catch {
+    // Telemetry must never break the gateway.
+  }
+}
+
+export async function shutdownAnalytics(): Promise<void> {
+  if (!client) return
+  try {
+    await client.shutdown(2000)
+  } catch {
+    // ignore
+  }
+}
+
+/**
+ * Install process-level handlers for uncaught exceptions and unhandled
+ * rejections so they're reported to PostHog before the process dies.
+ *
+ * Mirrors the CLI's `installGlobalErrorHandlers()` so runtime errors land
+ * in the same Switchroom Errors dashboard as CLI errors, tagged
+ * `source: 'gateway'`.
+ *
+ * The gateway already exits non-zero on fatal errors (see the polling
+ * IIFE at the bottom of gateway.ts). We DO NOT re-exit here for
+ * unhandledRejection — Node's default is to keep running and we want
+ * the gateway to keep polling. For uncaughtException we DO exit, because
+ * Node's default-since-v15 is to exit anyway after listeners return.
+ */
+export function installGlobalErrorHandlers(): void {
+  if (globalHandlersInstalled) return
+  globalHandlersInstalled = true
+
+  const FLUSH_TIMEOUT_MS = 2000
+
+  const flushWithTimeout = async (
+    error: unknown,
+    kind: 'uncaughtException' | 'unhandledRejection',
+  ): Promise<void> => {
+    await Promise.race([
+      captureException(error, { kind }),
+      new Promise<void>((resolve) => setTimeout(resolve, FLUSH_TIMEOUT_MS)),
+    ])
+  }
+
+  process.on('uncaughtException', (err) => {
+    process.stderr.write(`telegram gateway: uncaughtException: ${err}\n`)
+    void flushWithTimeout(err, 'uncaughtException').finally(() => {
+      process.exit(1)
+    })
+  })
+
+  process.on('unhandledRejection', (reason) => {
+    process.stderr.write(`telegram gateway: unhandledRejection: ${reason}\n`)
+    void flushWithTimeout(reason, 'unhandledRejection')
+  })
+}

package/telegram-plugin/bridge/bridge.ts

@@ -28,6 +28,7 @@ import {
 } from '../pty-tail.js'
 import { createIpcClient, type IpcClientHandle } from './ipc-client.js'
 import type { InboundMessage, PermissionEvent, StatusEvent } from '../gateway/ipc-protocol.js'
+import { matchesAllowRule } from '../permission-rule.js'
 
 installPluginLogger()
 
@@ -108,6 +109,7 @@ const TOOL_SCHEMAS = [
         disable_web_page_preview: { type: 'boolean', description: 'Disable link preview thumbnails. Default: true.' },
         protect_content: { type: 'boolean', description: 'When true, Telegram prevents the message from being forwarded or saved.' },
         quote_text: { type: 'string', description: 'Surgical quote: specific text to highlight from the reply_to message. Requires reply_to.' },
+        disable_notification: { type: 'boolean', description: 'When true, Telegram delivers the message silently — no device ping for this user. Default false (pings). Use true for mid-turn updates ("still working through X") so only the final answer pings. Always omit (or pass false) on the final answer of a turn.' },
         inline_keyboard: {
           type: 'array',
           description: 'Optional 2D array of tappable buttons rendered under the message. Outer array = rows; inner array = buttons in each row (max 8 per row, 8 rows). Each button needs a `text` (label, max 64 chars) plus EXACTLY ONE of: `url` (opens link in browser; must start with http(s):// or tg://) or `callback_data` (string, max 58 chars; tap is delivered to this agent as an inbound channel event with meta.button_callback_data=<the data> and the original button_text). Use buttons for single-tap approval/triage flows like [Approve] [Hold]; one tap on mobile beats asking the user to type YES/NO. By default a tap shows a brief "✓ received" toast and removes the entire keyboard so the user can\'t double-fire — override per-button via `ack_text` (custom toast text, max 200 chars) and `single_use: false` (preserve the keyboard so e.g. a [Refresh] button stays tappable).',
@@ -146,6 +148,7 @@ const TOOL_SCHEMAS = [
         quote: { type: 'boolean', description: 'Opt out of the default quote-reply behavior. Default: true. Ignored when reply_to is explicitly set.' },
         protect_content: { type: 'boolean', description: 'When true, Telegram prevents the message from being forwarded or saved.' },
         quote_text: { type: 'string', description: 'Surgical quote: specific text to highlight from the reply_to message. Requires reply_to.' },
+        disable_notification: { type: 'boolean', description: 'When true, the INITIAL message send is silent (no device ping). Has no effect on subsequent edits — Telegram never pings on editMessageText. Default false. Use for mid-turn stream starts you do not want to ping; omit on the final answer.' },
         inline_keyboard: {
           type: 'array',
           description: '2D array of tappable buttons under the final message. Same shape and constraints as `reply.inline_keyboard` — each button has `text` and EXACTLY ONE of `url` or `callback_data`, plus optional `ack_text` (custom tap-toast; default "✓ received") and `single_use` (default true; set false to keep the keyboard tappable after a tap). Tap on a callback_data button is delivered to this agent as an inbound channel event with meta.button_callback_data set.',
@@ -418,6 +421,23 @@ const TOOL_SCHEMAS = [
       required: ['chat_id', 'key', 'value'],
     },
   },
+  {
+    name: 'vault_request_access',
+    description:
+      'Ask the operator (via Telegram approval card) to grant this agent read or write access to a vault key it does not yet have. Use this when you hit `VAULT-BROKER-DENIED` or when you know upfront that an upcoming task needs a key you lack. Renders a [Approve] [Deny] card; on approve, the broker mints a scoped grant token and writes it to the agent\'s `.vault-token` file. You CANNOT mint or self-elevate; only the operator can tap Approve. After firing this tool, END YOUR TURN cleanly — the gateway will inject a fresh inbound message (with `<channel source="vault_grant_approved">`) when the operator approves, kicking off a new turn where you can resume the original task. Do NOT call this for keys you already have access to (use the normal `vault:<key>` reference) and do NOT spam-request (the operator sees every card).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        chat_id: { type: 'string', description: 'Chat to render the approval card in (use the chat_id of the user message that triggered the workflow).' },
+        key: { type: 'string', description: 'Vault key the agent wants access to (matches the key shown in the VAULT-BROKER-DENIED error, e.g. `fatsecret/credentials`).' },
+        scope: { type: 'string', enum: ['read', 'write'], description: 'Access scope: "read" (default) for `vault:<key>` references; "write" if the agent needs to put new values.' },
+        reason: { type: 'string', description: 'Short human-readable rationale rendered on the card (e.g. "to look up today\'s food log entries"). Helps the operator decide.' },
+        duration: { type: 'string', description: 'Requested grant TTL, like "30d" or "12h". Default 30d, capped at 90d. Beyond 90d the operator should use the host CLI explicitly.' },
+        message_thread_id: { type: 'string', description: 'Forum topic thread ID. Auto-applied from the last inbound message if not specified.' },
+      },
+      required: ['chat_id', 'key'],
+    },
+  },
 ]
 
 mcp.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOL_SCHEMAS }))
@@ -469,6 +489,22 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
 // approval. Forward them to the gateway which renders inline keyboard
 // buttons in the user's Telegram chat. The gateway sends the decision
 // back as a PermissionEvent which we relay to Claude Code (see onPermission).
+//
+// #1138: session-scoped always-allow cache. When the operator taps
+// "🔁 Always allow" the gateway calls `switchroom agent grant` which
+// updates settings.json on disk, but the running claude process won't
+// re-read that file — so a sub-agent (Task tool) dispatched later in
+// the same session still hits the popup. To close that gap the gateway
+// also broadcasts the resolved `rule` on the `permission` event and we
+// stash it here; subsequent `permission_request` notifications whose
+// (tool_name, input_preview) match a cached rule are auto-allowed
+// without a round-trip to Telegram. The cache lives for the bridge's
+// lifetime — which is the claude session's lifetime — so on the next
+// boot the now-persisted `tools.allow` entry takes over and this cache
+// is rebuilt as the operator approves things again. Parent claude and
+// every Task-tool sub-agent share the same bridge process, so a rule
+// added by either is honoured by all.
+const sessionAllowRules = new Set<string>()
 
 mcp.setNotificationHandler(
   z.object({
@@ -481,6 +517,28 @@ mcp.setNotificationHandler(
     }),
   }),
   async ({ params }) => {
+    // Cache hit? Auto-allow without bothering the gateway. We deliver
+    // the same `notifications/claude/channel/permission` shape claude
+    // would otherwise receive after a Telegram tap, so the call site
+    // is indistinguishable. We still notify the gateway out-of-band
+    // (via a permission_request that the gateway short-circuits on
+    // its side would be ideal, but for now skipping the forward is
+    // safe: pendingPermissions is a gateway-side bookkeeping map only,
+    // and nothing else depends on seeing this request_id).
+    for (const rule of sessionAllowRules) {
+      if (matchesAllowRule(rule, params.tool_name, params.input_preview)) {
+        process.stderr.write(
+          `telegram bridge: session-cached allow for ${params.tool_name} ` +
+          `(rule="${rule}", request_id=${params.request_id})\n`,
+        )
+        onPermission({
+          type: 'permission',
+          requestId: params.request_id,
+          behavior: 'allow',
+        })
+        return
+      }
+    }
     if (!ipc || !ipc.isConnected()) {
       process.stderr.write('telegram bridge: permission_request received but not connected to gateway\n')
       return
@@ -495,6 +553,7 @@ mcp.setNotificationHandler(
   },
 )
 
+
 // ─── IPC client ──────────────────────────────────────────────────────────
 
 let ipc: IpcClientHandle | null = null
@@ -513,6 +572,16 @@ function onInbound(msg: InboundMessage): void {
 }
 
 function onPermission(msg: PermissionEvent): void {
+  // #1138: stash the rule the gateway resolved on "Always allow" so we
+  // can short-circuit later matching permission_request notifications
+  // (from the parent claude or any Task-dispatched sub-agent in the
+  // same session). The gateway only sets `rule` when it has also
+  // persisted the rule to settings.json, so a process restart will
+  // pick up the same set of rules from disk — the cache is purely a
+  // mid-session bridge between the disk write and the next agent boot.
+  if (msg.rule) {
+    sessionAllowRules.add(msg.rule)
+  }
   mcp.notification({
     method: 'notifications/claude/channel/permission',
     params: {

package/telegram-plugin/bridge/ipc-client.ts

@@ -23,7 +23,10 @@ export function validateGatewayMessage(msg: unknown): msg is GatewayToClient {
       return typeof m.chatId === "string" && typeof m.text === "string";
     case "permission":
       return typeof m.requestId === "string"
-        && (m.behavior === "allow" || m.behavior === "deny");
+        && (m.behavior === "allow" || m.behavior === "deny")
+        // `rule` is optional (only sent on "🔁 Always allow"); when present
+        // it must be a non-empty string. #1138 wire extension.
+        && (m.rule === undefined || (typeof m.rule === "string" && m.rule.length > 0));
     case "status":
       return typeof m.status === "string";
     case "tool_call_result":