@cuongtran001/kanna 0.97.2 → 0.97.3

package/src/server/agent.openrouter-watchdog.test.ts

@@ -0,0 +1,280 @@
+import { describe, expect, test } from "bun:test"
+import { AgentCoordinator } from "./agent"
+import type { HarnessEvent } from "./harness-types"
+import type { LlmProviderSnapshot, SlashCommand, TranscriptEntry } from "../shared/types"
+import { AsyncEventQueue } from "./test-helpers/async-event-queue"
+import { waitFor } from "./test-helpers/wait-for"
+
+// Minimal store (trimmed copy from agent.openrouter-model.test.ts — do NOT
+// modify agent.test.ts).
+function createFakeStore() {
+  const chat = {
+    id: "chat-1",
+    projectId: "project-1",
+    title: "New Chat",
+    provider: null as string | null,
+    planMode: false,
+    sessionToken: null as string | null,
+    sessionTokensByProvider: {} as Record<string, string | null>,
+    slashCommands: undefined as SlashCommand[] | undefined,
+    pendingForkSessionToken: null as { provider: string; token: string } | null,
+  }
+  const project = { id: "project-1", localPath: "/tmp/project" }
+  return {
+    chat,
+    turnFailedCount: 0,
+    turnFailedReasons: [] as string[],
+    messages: [] as TranscriptEntry[],
+    queuedMessages: [] as Array<{ id: string; content: string }>,
+    async recordSessionCommandsLoaded(_chatId: string, commands: SlashCommand[]) {
+      chat.slashCommands = commands
+    },
+    requireChat() {
+      return chat
+    },
+    getChat(chatId: string) {
+      if (chatId !== "chat-1") return null
+      return chat
+    },
+    getProject() {
+      return project
+    },
+    getMessages() {
+      return this.messages
+    },
+    async setChatProvider(_chatId: string, provider: string) {
+      chat.provider = provider
+    },
+    async setPlanMode(_chatId: string, planMode: boolean) {
+      chat.planMode = planMode
+    },
+    async renameChat(_chatId: string, title: string) {
+      chat.title = title
+    },
+    async appendMessage(_chatId: string, entry: TranscriptEntry) {
+      this.messages.push(entry)
+    },
+    async recordTurnStarted() {},
+    async recordTurnFinished() {},
+    async recordTurnFailed(_chatId: string, reason: string) {
+      this.turnFailedCount += 1
+      this.turnFailedReasons.push(reason)
+    },
+    async recordTurnCancelled() {},
+    async setSessionToken(_chatId: string, sessionToken: string | null) {
+      chat.sessionToken = sessionToken
+    },
+    async setSessionTokenForProvider(_chatId: string, provider: string, sessionToken: string | null) {
+      chat.sessionTokensByProvider = { ...chat.sessionTokensByProvider, [provider]: sessionToken }
+      chat.sessionToken = sessionToken
+    },
+    async setPendingForkSessionToken(_chatId: string, value: { provider: string; token: string } | null) {
+      chat.pendingForkSessionToken = value
+    },
+    async createChat() {
+      return chat
+    },
+    async enqueueMessage() {
+      return { id: crypto.randomUUID(), content: "" }
+    },
+    getQueuedMessages() {
+      return [...this.queuedMessages]
+    },
+    *runningSubagentRuns() {},
+  }
+}
+
+function openrouterSnapshot(): LlmProviderSnapshot {
+  return {
+    provider: "openrouter",
+    apiKey: "sk-or-v1-abcdef1234567890",
+    model: "moonshotai/kimi-k2.5:nitro",
+    baseUrl: "",
+    resolvedBaseUrl: "https://openrouter.ai/api",
+    enabled: true,
+    warning: null,
+    filePathDisplay: "~/.kanna/llm-provider.json",
+  }
+}
+
+describe("AgentCoordinator OpenRouter first-entry watchdog", () => {
+  test(
+    "fails closed when the OpenRouter stream emits session_token then no entry",
+    async () => {
+      const events = new AsyncEventQueue<HarnessEvent>()
+      const store = createFakeStore()
+      let closeCalled = 0
+      const coordinator = new AgentCoordinator({
+        store: store as never,
+        onStateChange: () => {},
+        readLlmProvider: async () => openrouterSnapshot(),
+        openrouterFirstEntryTimeoutMs: 200,
+        startClaudeSession: async () => {
+          return {
+            provider: "claude",
+            stream: events,
+            getAccountInfo: async () => null,
+            interrupt: async () => {},
+            close: () => {
+              closeCalled += 1
+              events.close()
+            },
+            setModel: async () => {},
+            setPermissionMode: async () => {},
+            getSupportedCommands: async () => [],
+            // Never emit an entry — reproduces session a71516d4's silent stall
+            // where the SDK connected (account_info) but no system_init/result
+            // ever arrived.
+            sendPrompt: async () => {},
+          }
+        },
+      } as never)
+
+      await coordinator.send({
+        type: "chat.send",
+        chatId: "chat-1",
+        provider: "openrouter" as never,
+        content: "tell me about this project",
+        model: "qwen/qwen3.7-plus",
+      })
+
+      await waitFor(() => store.turnFailedCount > 0, 4000, "turn failed via watchdog")
+
+      expect(store.turnFailedCount).toBeGreaterThan(0)
+      expect(closeCalled).toBeGreaterThan(0)
+      const errorResult = store.messages.find(
+        (m) => m.kind === "result" && (m as { isError?: boolean }).isError === true,
+      )
+      expect(errorResult).toBeDefined()
+      expect((errorResult as { result?: string }).result).toContain("OpenRouter produced no response")
+    },
+    10_000,
+  )
+
+  test(
+    "does not fail the turn when the OpenRouter stream emits an entry in time",
+    async () => {
+      const events = new AsyncEventQueue<HarnessEvent>()
+      const store = createFakeStore()
+      const coordinator = new AgentCoordinator({
+        store: store as never,
+        onStateChange: () => {},
+        readLlmProvider: async () => openrouterSnapshot(),
+        openrouterFirstEntryTimeoutMs: 200,
+        startClaudeSession: async () => {
+          // Emit a result entry promptly — the watchdog must be cleared and
+          // never fire.
+          events.push({
+            type: "transcript",
+            entry: {
+              _id: "result-1",
+              createdAt: Date.now(),
+              kind: "result",
+              subtype: "success",
+              isError: false,
+              durationMs: 0,
+              result: "done",
+            } as never,
+          })
+          return {
+            provider: "claude",
+            stream: events,
+            getAccountInfo: async () => null,
+            interrupt: async () => {},
+            close: () => events.close(),
+            setModel: async () => {},
+            setPermissionMode: async () => {},
+            getSupportedCommands: async () => [],
+            sendPrompt: async () => {},
+          }
+        },
+      } as never)
+
+      await coordinator.send({
+        type: "chat.send",
+        chatId: "chat-1",
+        provider: "openrouter" as never,
+        content: "hi",
+        model: "moonshotai/kimi-k2.5:nitro",
+      })
+
+      // Wait past the watchdog window; the timely entry must keep it disarmed.
+      await new Promise((resolve) => setTimeout(resolve, 500))
+
+      expect(store.turnFailedCount).toBe(0)
+      const errorResult = store.messages.find(
+        (m) => m.kind === "result" && (m as { isError?: boolean }).isError === true,
+      )
+      expect(errorResult).toBeUndefined()
+    },
+    10_000,
+  )
+})
+
+describe("AgentCoordinator OpenRouter SDK-session prompt delivery", () => {
+  test(
+    "delivers the user prompt to the SDK session for openrouter (regression: prompt-delivery gate)",
+    async () => {
+      // Regression for the gate that delivered prompts only when
+      // `provider === "claude"`. OpenRouter rides the same SDK session but was
+      // excluded, so its prompt never reached `sendPrompt` and every turn hung
+      // until the watchdog. `providerUsesSdkSession` now covers both.
+      const events = new AsyncEventQueue<HarnessEvent>()
+      const store = createFakeStore()
+      const sentPrompts: string[] = []
+      const coordinator = new AgentCoordinator({
+        store: store as never,
+        onStateChange: () => {},
+        readLlmProvider: async () => openrouterSnapshot(),
+        openrouterFirstEntryTimeoutMs: 5000,
+        startClaudeSession: async () => {
+          return {
+            provider: "claude",
+            stream: events,
+            getAccountInfo: async () => null,
+            interrupt: async () => {},
+            close: () => events.close(),
+            setModel: async () => {},
+            setPermissionMode: async () => {},
+            getSupportedCommands: async () => [],
+            sendPrompt: async (content: string) => {
+              sentPrompts.push(content)
+              // A real upstream would now stream a turn; emit a success result
+              // so the turn completes cleanly and the watchdog never fires.
+              events.push({
+                type: "transcript",
+                entry: {
+                  _id: "result-1",
+                  createdAt: Date.now(),
+                  kind: "result",
+                  subtype: "success",
+                  isError: false,
+                  durationMs: 0,
+                  result: "ok",
+                } as never,
+              })
+            },
+          }
+        },
+      } as never)
+
+      await coordinator.send({
+        type: "chat.send",
+        chatId: "chat-1",
+        provider: "openrouter" as never,
+        content: "hello openrouter",
+        model: "moonshotai/kimi-k2.5:nitro",
+      })
+
+      await waitFor(
+        () => sentPrompts.some((p) => p.includes("hello openrouter")),
+        4000,
+        "openrouter prompt delivered to the SDK session",
+      )
+
+      expect(sentPrompts.some((p) => p.includes("hello openrouter"))).toBe(true)
+      expect(store.turnFailedCount).toBe(0)
+    },
+    10_000,
+  )
+})

package/src/server/agent.ts

@@ -48,7 +48,7 @@ import {
   openrouterAuthReady,
 } from "./provider-catalog"
 import { readLlmProviderSnapshot } from "./llm-provider"
-import { resolveClaudeApiModelId, type ClaudeDriverPreference } from "../shared/types"
+import { providerUsesSdkSession, resolveClaudeApiModelId, type ClaudeDriverPreference } from "../shared/types"
 import { fallbackTitleFromMessage } from "./generate-title"
 import { AUTO_CONTINUE_EVENT_VERSION, type AutoContinueEvent } from "./auto-continue/events"
 import { ClaudeLimitDetector, CodexLimitDetector, type LimitDetection, type LimitDetector } from "./auto-continue/limit-detector"
@@ -340,6 +340,17 @@ interface AgentCoordinatorArgs {
    * 120000 (2 min). Bounded by `maxAgentWakes`.
    */
   pendingWorkflowPollMs?: number
+  /**
+   * Watchdog (ms) for an OpenRouter turn whose SDK stream emits no transcript
+   * entry (no `system_init`) after the session-token handshake. OpenRouter
+   * routes through the Claude SDK; a stalled upstream leaves the stream open
+   * but silent, so the `runClaudeSession` for-await never returns or throws
+   * and the existing fail-close never fires. On timeout the watchdog
+   * interrupts + closes the session so the stream ends and the turn is
+   * recorded failed. OpenRouter-only; cleared on the first entry. Default
+   * 120000 (2 min).
+   */
+  openrouterFirstEntryTimeoutMs?: number
   getSubagents?: () => Subagent[]
   getAppSettingsSnapshot?: () => {
     claudeAuth?: { authenticated?: boolean } | null
@@ -1324,6 +1335,12 @@ const DEFAULT_CLAUDE_SESSION_SWEEP_INTERVAL_MS = 60 * 1000
 // Keep a PTY session warm up to 30 min while a background Bash task is pending —
 // comfortably longer than the 10-min idle window and typical CI durations.
 const DEFAULT_PTY_BACKGROUND_TASK_MAX_MS = 30 * 60 * 1000
+// OpenRouter-only watchdog: a stalled upstream leaves the SDK stream open but
+// silent after the session-token handshake, so the runClaudeSession for-await
+// never ends and the existing fail-close never fires. Abort if no transcript
+// entry arrives within this window. system_init is the SDK init echo (precedes
+// model inference), so 2 min is generous; env-tunable per deployment.
+const DEFAULT_OPENROUTER_FIRST_ENTRY_TIMEOUT_MS = 2 * 60 * 1000
 // Agent wakes are clamped to one idle window minus this buffer so a re-entry
 // always lands before the idle reaper closes the PTY (see scheduleAgentWakeup).
 const WAKE_GUARD_BUFFER_MS = 60 * 1000
@@ -1412,6 +1429,7 @@ export class AgentCoordinator {
   private readonly agentWakeChainByChat = new Map<string, number>()
   private readonly maxAgentWakes: number
   private readonly pendingWorkflowPollMs: number
+  private readonly openrouterFirstEntryTimeoutMs: number
   // Per-tokenId rotation dedupe state. When a shared OAuth token throws
   // limit/auth-error against N chats simultaneously, only the first chat
   // pays the cost of marking the pool + picking a fresh target; subsequent
@@ -1456,6 +1474,8 @@ export class AgentCoordinator {
     this.getAutoResumePreference = args.getAutoResumePreference ?? (() => false)
     this.maxAgentWakes = args.maxAgentWakes ?? 25
     this.pendingWorkflowPollMs = args.pendingWorkflowPollMs ?? 120_000
+    this.openrouterFirstEntryTimeoutMs =
+      args.openrouterFirstEntryTimeoutMs ?? DEFAULT_OPENROUTER_FIRST_ENTRY_TIMEOUT_MS
     this.getSubagents = args.getSubagents ?? (() => [])
     this.getAppSettingsSnapshot = args.getAppSettingsSnapshot ?? (() => ({}))
     this.readLlmProvider = args.readLlmProvider ?? readLlmProviderSnapshot
@@ -2446,10 +2466,13 @@ export class AgentCoordinator {
         .catch(() => undefined)
     }
 
-    if (args.provider === "claude") {
+    if (providerUsesSdkSession(args.provider)) {
+      // claude and openrouter both deliver their prompt through the SDK
+      // session queue; gating this on `=== "claude"` is what left openrouter's
+      // prompt undelivered, hanging every openrouter turn until the watchdog.
       const session = this.claudeSessions.get(args.chatId)
       if (!session) {
-        throw new Error("Claude session was not initialized")
+        throw new Error("SDK session was not initialized")
       }
       const promptSeq = session.nextPromptSeq + 1
       session.nextPromptSeq = promptSeq
@@ -2487,12 +2510,12 @@ export class AgentCoordinator {
     planMode: boolean
     clientTraceId?: string
   }): ActiveTurn | undefined {
-    if (args.provider !== "claude") return undefined
+    if (!providerUsesSdkSession(args.provider)) return undefined
     const session = this.claudeSessions.get(args.chatId)
     if (!session) return undefined
 
     const ghostTurn: HarnessTurn = {
-      provider: "claude",
+      provider: args.provider,
       stream: { async *[Symbol.asyncIterator]() {} },
       getAccountInfo: session.session.getAccountInfo,
       interrupt: session.session.interrupt,
@@ -3089,6 +3112,56 @@ export class AgentCoordinator {
   }
 
   private async runClaudeSession(session: ClaudeSessionState) {
+    // OpenRouter-only first-entry watchdog. OpenRouter routes through the
+    // Claude SDK; a stalled upstream emits the session-token handshake then
+    // goes silent — the stream stays open with no entry, so this for-await
+    // never returns or throws and the chat hangs "running" until restart. The
+    // existing catch/finally fail-close is claude-provider-gated and depends
+    // on an active turn that the openrouter path tears down early, so the
+    // watchdog records the failure itself, then interrupts + closes the
+    // session to end the stream. `firstEntrySeen` guards against a late real
+    // entry; close() prevents any further entry from being processed.
+    const isOpenRouterSession = session.openrouterModel !== null
+    let firstEntrySeen = false
+    let firstEntryWatchdog: ReturnType<typeof setTimeout> | null = null
+    const clearFirstEntryWatchdog = () => {
+      if (firstEntryWatchdog !== null) {
+        clearTimeout(firstEntryWatchdog)
+        firstEntryWatchdog = null
+      }
+    }
+    if (isOpenRouterSession) {
+      firstEntryWatchdog = setTimeout(() => {
+        if (firstEntrySeen) return
+        if (this.claudeSessions.get(session.chatId) !== session) return
+        firstEntrySeen = true
+        const message = `OpenRouter produced no response within ${this.openrouterFirstEntryTimeoutMs}ms — the selected model may be invalid or the upstream stalled.`
+        console.warn("[kanna/agent] openrouter stream produced no entry within watchdog window — failing turn", {
+          chatId: session.chatId,
+          sessionId: session.id,
+          model: session.openrouterModel,
+          timeoutMs: this.openrouterFirstEntryTimeoutMs,
+        })
+        void (async () => {
+          await this.store.appendMessage(
+            session.chatId,
+            timestamped({
+              kind: "result",
+              subtype: "error",
+              isError: true,
+              durationMs: this.openrouterFirstEntryTimeoutMs,
+              result: message,
+            }),
+          )
+          await this.store.recordTurnFailed(session.chatId, message)
+          const active = this.activeTurns.get(session.chatId)
+          if (active) this.activeTurns.delete(session.chatId)
+          this.emitStateChange(session.chatId)
+          void session.session.interrupt().catch(() => {})
+          session.session.close()
+        })()
+      }, this.openrouterFirstEntryTimeoutMs)
+    }
     try {
       let simulateLimit = this.throwOnClaudeSessionStart
       for await (const event of session.session.stream) {
@@ -3119,6 +3192,8 @@ export class AgentCoordinator {
         }
 
         if (!event.entry) continue
+        firstEntrySeen = true
+        clearFirstEntryWatchdog()
         if (this.claudeSessions.get(session.chatId) !== session) break
         // Suppress the interrupt-induced tail `result` of a cancelled turn.
         // cancel() already removed the active turn, recorded the cancellation,
@@ -3337,6 +3412,7 @@ export class AgentCoordinator {
         }
       }
     } finally {
+      clearFirstEntryWatchdog()
       const active = this.activeTurns.get(session.chatId)
       const isCurrentSession = this.claudeSessions.get(session.chatId) === session
       // Trace point: stream-end-without-final-result is the hang signature.

package/src/server/server.ts

@@ -432,6 +432,10 @@ export async function startKannaServer(options: StartKannaServerOptions = {}) {
     scheduleManager,
     maxAgentWakes: parsePositiveIntEnv(process.env.KANNA_MAX_AGENT_WAKES, 25),
     pendingWorkflowPollMs: parsePositiveIntEnv(process.env.KANNA_PENDING_WORKFLOW_POLL_MS, 120_000),
+    openrouterFirstEntryTimeoutMs: parsePositiveIntEnv(
+      process.env.KANNA_OPENROUTER_FIRST_ENTRY_TIMEOUT_MS,
+      2 * 60 * 1000,
+    ),
     claudeLimitDetector: options.agentOverrides?.claudeLimitDetector,
     codexLimitDetector: options.agentOverrides?.codexLimitDetector,
     throwOnClaudeSessionStart: options.agentOverrides?.throwOnClaudeSessionStart,

package/src/shared/types.ts

@@ -425,6 +425,22 @@ export function getProviderCatalog(provider: AgentProvider): ProviderCatalogEntr
   return entry
 }
 
+/**
+ * True when the provider's turns run through the Claude SDK session transport
+ * (a live `claudeSessions` entry consumed by `runClaudeSession`, prompts
+ * delivered via `session.sendPrompt`) rather than the generic harness-turn
+ * transport (`runTurn` over `active.turn.stream`).
+ *
+ * `claude` and `openrouter` both ride the SDK session — openrouter just points
+ * the SDK at OpenRouter's Anthropic-compatible endpoint. Branching on
+ * `provider === "claude"` where the real intent is "uses the SDK session" is
+ * what silently dropped openrouter's prompt delivery; use this predicate so a
+ * new SDK-backed provider can never be forgotten by an `if`-chain again.
+ */
+export function providerUsesSdkSession(provider: AgentProvider): boolean {
+  return provider === "claude" || provider === "openrouter"
+}
+
 function getProviderModelMatch(provider: AgentProvider, modelId?: string): ProviderModelOption | undefined {
   if (!modelId) return undefined
 

package/dist/client/assets/channel-ohENpLj7.js

@@ -1 +0,0 @@
-import{U as a,D as n}from"./mermaid.core-CoJEFYct.js";const t=(r,o)=>a.lang.round(n.parse(r)[o]);export{t as c};

package/dist/client/assets/classDiagram-4FO5ZUOK-BlyPnDJH.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-727SXJPM-eMaVSOKi.js";import{_ as i}from"./mermaid.core-CoJEFYct.js";import"./chunk-FMBD7UC4-BtAWu6Fv.js";import"./chunk-ND2GUHAM-CyxbGgpO.js";import"./chunk-55IACEB6-HUFJLmvp.js";import"./chunk-2J33WTMH-C77Np9ft.js";import"./index-MixgFXRr.js";var n={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{n as diagram};

package/dist/client/assets/classDiagram-v2-Q7XG4LA2-BlyPnDJH.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-727SXJPM-eMaVSOKi.js";import{_ as i}from"./mermaid.core-CoJEFYct.js";import"./chunk-FMBD7UC4-BtAWu6Fv.js";import"./chunk-ND2GUHAM-CyxbGgpO.js";import"./chunk-55IACEB6-HUFJLmvp.js";import"./chunk-2J33WTMH-C77Np9ft.js";import"./index-MixgFXRr.js";var n={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{n as diagram};

package/dist/client/assets/stateDiagram-v2-BHNVJYJU-BRLtys3w.js

@@ -1 +0,0 @@
-import{s as e,b as r,a,S as s}from"./chunk-AQP2D5EJ-Dqr7iBWK.js";import{_ as i}from"./mermaid.core-CoJEFYct.js";import"./chunk-55IACEB6-HUFJLmvp.js";import"./chunk-2J33WTMH-C77Np9ft.js";import"./index-MixgFXRr.js";var p={parser:a,get db(){return new s(2)},renderer:r,styles:e,init:i(t=>{t.state||(t.state={}),t.state.arrowMarkerAbsolute=t.arrowMarkerAbsolute},"init")};export{p as diagram};