@0xmaxma/claude-gateway 1.3.25 → 1.3.32

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.25",
+  "version": "1.3.32",
   "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",