@0xmaxma/claude-gateway 1.3.24 → 1.3.31

package/mcp/tools/telegram/skills/configure/SKILL.md

@@ -51,46 +51,44 @@ Read both state files and give the user a complete picture:
    (`123456789:...`).
 
 2. **Access** — read `{STATE_DIR}/access.json` (missing file
-   = defaults: `dmPolicy: "pairing"`, empty allowlist). Show:
-   - DM policy and what it means in one line
+   = defaults: `dmPolicy: "allowlist"`, `pairing: true`, empty allowlist). Show:
+   - DM policy (`open`/`allowlist`/`disabled`) and what it means in one line
+   - Pairing toggle (on/off) and what it means in one line
    - Allowed senders: count, and list display names or IDs
    - Pending pairings: count, with codes and display names if any
 
 3. **What next** — end with a concrete next step based on state:
    - No token → *"Run `/telegram:configure <token>` with the token from
      BotFather."*
-   - Token set, policy is pairing, nobody allowed → *"DM your bot on
-     Telegram. It replies with a code; approve with `/telegram:access pair
-     <code>`."*
+   - Token set, `allowlist` + pairing on, nobody allowed → *"DM your bot on
+     Telegram. It replies with a code — approve it from the web Channels card
+     (or run `/telegram:access pair <code>` here)."*
    - Token set, someone allowed → *"Ready. DM your bot to reach the
      assistant."*
 
-**Push toward lockdown — always.** The goal for every setup is `allowlist`
-with a defined list. `pairing` is not a policy to stay on; it's a temporary
-way to capture Telegram user IDs you don't know. Once the IDs are in, pairing
-has done its job and should be turned off.
+**The access model.** The base policy should be `allowlist` — only people on
+the list reach the assistant. **Pairing** is an orthogonal on/off toggle
+(default on) that sits on top of `allowlist`: when on, an unknown sender who
+DMs the bot gets a one-time code that shows up in Pending, and the admin
+approves it (from the web Channels card, or `/telegram:access pair <code>`).
+It's a lightweight identity check, and it's fine to leave on as your standing
+way to let new people in. Turn pairing **off** only if you want a hard
+allowlist where strangers are dropped silently with no code.
 
 Drive the conversation this way:
 
 1. Read the allowlist. Tell the user who's in it.
 2. Ask: *"Is that everyone who should reach you through this bot?"*
-3. **If yes and policy is still `pairing`** → *"Good. Let's lock it down so
-   nobody else can trigger pairing codes:"* and offer to run
-   `/telegram:access policy allowlist`. Do this proactively — don't wait to
-   be asked.
-4. **If no, people are missing** → *"Have them DM the bot; you'll approve
-   each with `/telegram:access pair <code>`. Run this skill again once
-   everyone's in and we'll lock it."*
-5. **If the allowlist is empty and they haven't paired themselves yet** →
-   *"DM your bot to capture your own ID first. Then we'll add anyone else
-   and lock it down."*
-6. **If policy is already `allowlist`** → confirm this is the locked state.
-   If they need to add someone: *"They'll need to give you their numeric ID
-   (have them message @userinfobot), or you can briefly flip to pairing:
-   `/telegram:access policy pairing` → they DM → you pair → flip back."*
-
-Never frame `pairing` as the correct long-term choice. Don't skip the lockdown
-offer.
+3. **If someone's missing** → *"Leave pairing on: have them DM the bot, then
+   approve the code that appears in Pending (web card or `/telegram:access
+   pair <code>`)."*
+4. **If the allowlist is empty and they haven't paired themselves yet** →
+   *"DM your bot to capture your own ID first — approve the code and you're
+   in."*
+5. **If they want a hard lockdown** (no new codes for strangers) → offer to
+   run `/telegram:access pairing off`. This keeps `allowlist` but stops
+   minting codes; add people later by flipping pairing back on, or with
+   `/telegram:access allow <senderId>`.
 
 ### `<token>` — save it
 
@@ -116,3 +114,10 @@ Delete the `TELEGRAM_BOT_TOKEN=` line (or the file if that's the only line).
   or `/reload-plugins`. Say so after saving.
 - `access.json` is re-read on every inbound message — policy changes via
   `/telegram:access` take effect immediately, no restart.
+- **Groups need more than allowlisting.** DMs work over long-polling, but in a
+  group Telegram's default **Privacy Mode** stops the bot from receiving plain
+  messages (it only gets `/commands`, @mentions, and replies), and commands are
+  dropped in groups anyway. To use groups, tell the user to promote the bot to
+  **Admin** in the group (or disable Privacy Mode in BotFather and re-add it),
+  then allowlist the group via `/telegram:access` (pairing code or `group allow
+  <groupId>`).

package/mcp/tools/telegram/typing.ts

@@ -13,6 +13,17 @@
  *   STATE_DIR/typing/{chatId}.error     — written by AgentRunner on session failure
  */
 
+// Import compiled dist/, not raw src/ — src/ is not published (files: ["mcp/"]),
+// so a src/ import crashes this bun-run tool on installed packages. Enforced by
+// tests/unit/mcp-no-src-imports.test.ts.
+import {
+  classifyTurn,
+  type TurnObservation,
+  type TurnStage,
+  type TurnIncidentSink,
+  type TurnIncidentEvidence,
+} from '../../../dist/agent/turn-trace.js'
+
 export const TELEGRAM_MAX_CHARS = 4096
 
 /**
@@ -145,6 +156,10 @@ export const ERROR_MESSAGES: Record<string, string> = {
   PROCESS_FAILED: '❌ Claude stopped unexpectedly. Please try sending a new message.',
   POOL_FULL: '⚠️ Too many concurrent sessions. Please try again in a moment.',
   SPAWN_FAILED: '❌ Failed to start Claude session. Please try again.',
+  // Epic #195, Phase 3: the interactive backend failed repeatedly, so the agent
+  // temporarily fell back to the headless backend to keep serving.
+  SAFE_MODE_ENABLED:
+    '⚠️ The interactive backend kept failing, so I switched to safe mode (headless) for now. Please resend your message — it should go through.',
 }
 
 export const STATUS_EMOJI: Record<string, string> = {
@@ -177,6 +192,10 @@ export interface WorkingState {
   currentReaction: string | null
   lastDetail: string | null
   recentDetails: string[]
+  /** Last stage an incident was raised for — dedupes the turn-trace watchdog
+   *  so one contiguous stalled episode emits a single incident, not one per
+   *  15s tick. Reset to null once the turn is no longer stalled. */
+  lastIncidentStage: TurnStage | null
 }
 
 export interface BotApi {
@@ -295,6 +314,7 @@ export function createWorkingStateManager(
   typingDir: string,
   botApi: BotApi,
   fsApi: FsApi,
+  onIncident?: TurnIncidentSink,
 ) {
   const states = new Map<string, WorkingState>()
 
@@ -330,6 +350,106 @@ export function createWorkingStateManager(
     return `${typingDir}/${chatId}.replied`
   }
 
+  function menuFilePath(chatId: string): string {
+    return `${typingDir}/${chatId}.menu`
+  }
+
+  // ─── Turn-trace watchdog (Epic #195, Phase 1) ──────────────────────────────
+  // Read-only: builds an observation of this turn's on-disk artifacts, classifies
+  // the current pipeline stage, and emits a (silent) incident when a stage stalls.
+  // It never mutates state or messages the user — the existing heartbeat warn/stop
+  // below remains the sole user-facing stalled behaviour.
+
+  function statMtime(path: string): number | null {
+    try {
+      return fsApi.existsSync(path) ? fsApi.statSync(path).mtimeMs : null
+    } catch {
+      return null
+    }
+  }
+
+  function readTurnObservation(chatId: string, startedAt: number): TurnObservation {
+    let statusLabel: string | null = null
+    const statusPath = statusFilePath(chatId)
+    if (fsApi.existsSync(statusPath)) {
+      try {
+        statusLabel = parseStatusFile(fsApi.readFileSync(statusPath, 'utf8')).status
+      } catch {}
+    }
+    return {
+      now: Date.now(),
+      // A live WorkingState means the signal file was written at startedAt.
+      signalAt: fsApi.existsSync(typingFilePath(chatId)) ? startedAt : null,
+      statusLabel,
+      heartbeatAt: statMtime(heartbeatFilePath(chatId)),
+      processingAt: statMtime(processingFilePath(chatId)),
+      forwardAt: statMtime(forwardFilePath(chatId)),
+      menuAt: statMtime(menuFilePath(chatId)),
+      repliedPresent: fsApi.existsSync(repliedFilePath(chatId)),
+      errorPresent: fsApi.existsSync(errorFilePath(chatId)),
+    }
+  }
+
+  function readFileSafe(path: string): string | null {
+    try {
+      return fsApi.existsSync(path) ? fsApi.readFileSync(path, 'utf8') : null
+    } catch {
+      return null
+    }
+  }
+
+  // Build the diagnostic evidence bundle for an incident from the same
+  // observation the classifier used, plus the raw status/error file contents.
+  // Cheap and read-only — no listing of the whole typing dir, just this turn's
+  // known artifacts. The store scrubs everything before it is persisted.
+  function readTurnEvidence(chatId: string, obs: TurnObservation): TurnIncidentEvidence {
+    const artifacts: string[] = []
+    if (obs.signalAt !== null) artifacts.push('signal')
+    if (obs.statusLabel !== null) artifacts.push(`status=${obs.statusLabel}`)
+    if (obs.heartbeatAt !== null) artifacts.push('heartbeat')
+    if (obs.processingAt !== null) artifacts.push('processing')
+    if (obs.forwardAt !== null) artifacts.push('forward')
+    if (obs.menuAt !== null) artifacts.push('menu')
+    if (obs.repliedPresent) artifacts.push('replied')
+    if (obs.errorPresent) artifacts.push('error')
+    return {
+      artifacts,
+      statusText: readFileSafe(statusFilePath(chatId)),
+      errorText: readFileSafe(errorFilePath(chatId)),
+    }
+  }
+
+  function checkTurnTrace(chatId: string, startedAt: number): void {
+    const state = states.get(chatId)
+    if (!state) return
+    const obs = readTurnObservation(chatId, startedAt)
+    const trace = classifyTurn(obs)
+    if (!trace.stalled) {
+      state.lastIncidentStage = null
+      return
+    }
+    // Dedupe: one incident per contiguous stalled-stage episode.
+    if (state.lastIncidentStage === trace.stage) return
+    state.lastIncidentStage = trace.stage
+    if (onIncident) {
+      // A fresh .processing sentinel (mtime >= startedAt) means the turn is
+      // genuinely mid-work (e.g. a long sub-agent), not silently wedged.
+      const midTurn = obs.processingAt !== null && obs.processingAt >= startedAt
+      onIncident(
+        {
+          chatId,
+          stage: trace.stage,
+          failureClass: trace.failureClass,
+          sinceMs: trace.sinceMs,
+          budgetMs: trace.budgetMs,
+          midTurn,
+          at: Date.now(),
+        },
+        readTurnEvidence(chatId, obs),
+      )
+    }
+  }
+
   async function stop(chatId: string): Promise<void> {
     const state = states.get(chatId)
     if (!state) return
@@ -430,6 +550,7 @@ export function createWorkingStateManager(
       currentReaction: null,
       lastDetail: null,
       recentDetails: [],
+      lastIncidentStage: null,
     }
     states.set(chatId, state)
 
@@ -530,6 +651,9 @@ export function createWorkingStateManager(
     // Heartbeat file is written by SessionProcess on every Claude stdout line.
     state.stalledInterval = setInterval(async () => {
       if (!states.has(chatId)) return
+      // Turn-trace watchdog: staged classification + incident telemetry. Silent
+      // and side-effect-free — the heartbeat warn/stop below is unchanged.
+      checkTurnTrace(chatId, startedAt)
       const hbPath = heartbeatFilePath(chatId)
       let lastActivity = startedAt
       if (fsApi.existsSync(hbPath)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0xmaxma/claude-gateway",
-  "version": "1.3.24",
+  "version": "1.3.31",
   "description": "Multi-agent gateway for Claude",
   "repository": {
     "type": "git",
@@ -28,7 +28,9 @@
     "build": "tsc",
     "start": "node --no-warnings=ExperimentalWarning --env-file-if-exists=.env dist/index.js",
     "postinstall": "if command -v bun >/dev/null 2>&1; then bun install --cwd mcp; else echo 'Warning: bun not found. Run `cd mcp && bun install` manually to enable MCP tools.'; fi",
+    "pretest": "npm run build",
     "test": "jest",
+    "pretest:unit": "npm run build",
     "test:unit": "jest --testPathPattern=unit",
     "test:e2e": "jest --testPathPattern=tests/e2e --forceExit",
     "integration": "jest --testPathPattern=integration --testTimeout=15000",