@cuongtran001/kanna 1.3.0 → 1.4.0

package/src/server/claude-session-state-queries.ts

@@ -0,0 +1,160 @@
+/**
+ * Standalone session-state query helpers and idle-reaper for AgentCoordinator.
+ *
+ * Extracted from agent.ts so the query logic lives in its own testable module.
+ * The coordinator delegates to these functions by passing an object literal
+ * that satisfies `SessionStateQueryDeps`.
+ *
+ * Side-effect seal: this module contains NO direct IO (no node:fs, no HTTP
+ * calls, no Bun primitives). Every effectful operation is injected through
+ * the deps interface.
+ */
+
+import type { AgentProvider, KannaStatus, PendingToolSnapshot } from "../shared/types"
+import type { ActiveTurn, ClaudeSessionState } from "./claude-session-state"
+
+// ---------------------------------------------------------------------------
+// Deps interface
+// ---------------------------------------------------------------------------
+
+export interface SessionStateQueryDeps {
+  /** Live turn state keyed by chatId. */
+  activeTurns: Map<string, ActiveTurn>
+  /** Live Claude session state keyed by chatId. */
+  claudeSessions: Map<string, ClaudeSessionState>
+  /** Streams currently draining (only `.keys()` is consumed). */
+  drainingStreams: { keys(): IterableIterator<string> }
+  /** chatIds with a slash-commands load in-flight. */
+  slashCommandsInFlight: ReadonlySet<string>
+  /** Returns true when the given provider is a Claude SDK provider. */
+  isClaudeSdkProvider: (provider: AgentProvider) => boolean
+  /** Returns true when the session has a pending background Bash task. */
+  hasPendingBackgroundTask: (session: ClaudeSessionState, now: number) => boolean
+  /** Resolves the effective idle timeout in milliseconds. */
+  resolveClaudeIdleMs: () => number
+  /** Returns true when the chat has an in-flight Workflow. */
+  hasLiveWorkflow: (chatId: string) => boolean
+  /** Tears down and cleans up a Claude session. */
+  closeClaudeSession: (chatId: string, session: ClaudeSessionState) => void
+  /** Notifies subscribers that state has changed for the given chat. */
+  emitStateChange: (chatId: string) => void
+}
+
+// ---------------------------------------------------------------------------
+// Public query functions
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns a map of chatId → KannaStatus for all currently active turns.
+ */
+export function getActiveStatuses(deps: SessionStateQueryDeps): Map<string, KannaStatus> {
+  const statuses = new Map<string, KannaStatus>()
+  for (const [chatId, turn] of deps.activeTurns.entries()) {
+    statuses.set(chatId, turn.status)
+  }
+  return statuses
+}
+
+/**
+ * Returns a map of chatId → waitStartedAt for turns that are currently
+ * waiting (i.e. have a non-null waitStartedAt).
+ */
+export function getWaitStartedAtByChatId(deps: SessionStateQueryDeps): Map<string, number> {
+  const out = new Map<string, number>()
+  for (const [chatId, turn] of deps.activeTurns.entries()) {
+    if (turn.waitStartedAt != null) out.set(chatId, turn.waitStartedAt)
+  }
+  return out
+}
+
+/**
+ * Returns the pending tool snapshot for the active turn in the given chat,
+ * or null if there is no active turn or no pending tool.
+ */
+export function getPendingTool(
+  deps: SessionStateQueryDeps,
+  chatId: string,
+): PendingToolSnapshot | null {
+  const pending = deps.activeTurns.get(chatId)?.pendingTool
+  if (!pending) return null
+  return { toolUseId: pending.toolUseId, toolKind: pending.tool.toolKind }
+}
+
+/**
+ * Returns the set of chatIds whose streams are currently draining.
+ */
+export function getDrainingChatIds(deps: SessionStateQueryDeps): Set<string> {
+  return new Set(deps.drainingStreams.keys())
+}
+
+/**
+ * Returns the set of chatIds that have a slash-commands load in-flight.
+ */
+export function getSlashCommandsLoadingChatIds(deps: SessionStateQueryDeps): Set<string> {
+  return new Set(deps.slashCommandsInFlight)
+}
+
+/**
+ * Snapshot of live Claude session states per chat. Used by the sidebar badge
+ * selector. Chats not present in the returned map are implicitly `cold`.
+ */
+export function getClaudeSessionStates(
+  deps: SessionStateQueryDeps,
+): Map<string, "warming" | "active" | "idle"> {
+  const out = new Map<string, "warming" | "active" | "idle">()
+  const now = Date.now()
+  for (const [chatId, session] of deps.claudeSessions) {
+    const activeProv = deps.activeTurns.get(chatId)?.provider
+    if (activeProv !== undefined && deps.isClaudeSdkProvider(activeProv)) {
+      out.set(chatId, "active")
+    } else if (deps.hasPendingBackgroundTask(session, now)) {
+      // Held warm for a background Bash task — surface as "warming", not "idle".
+      out.set(chatId, "warming")
+    } else if (now - session.lastUsedAt >= deps.resolveClaudeIdleMs()) {
+      out.set(chatId, "idle")
+    } else {
+      out.set(chatId, "warming")
+    }
+  }
+  return out
+}
+
+// ---------------------------------------------------------------------------
+// Idle-reaper helpers (private semantics preserved as package functions)
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true when the given Claude session has no live activity and the
+ * idle timeout has elapsed since it was last used.
+ *
+ * Mirrors the private `isClaudeSessionIdle` on AgentCoordinator.
+ */
+export function isClaudeSessionIdle(
+  deps: SessionStateQueryDeps,
+  chatId: string,
+  session: ClaudeSessionState,
+  now = Date.now(),
+): boolean {
+  const activeProv = deps.activeTurns.get(chatId)?.provider
+  if (activeProv !== undefined && deps.isClaudeSdkProvider(activeProv)) return false
+  if (session.pendingPromptSeqs.length > 0) return false
+  if (deps.hasLiveWorkflow(chatId)) return false
+  if (deps.hasPendingBackgroundTask(session, now)) return false
+  return now - session.lastUsedAt >= deps.resolveClaudeIdleMs()
+}
+
+/**
+ * Iterates all live Claude sessions and closes any that are idle.
+ *
+ * Mirrors the private `sweepIdleClaudeSessions` on AgentCoordinator.
+ */
+export function sweepIdleClaudeSessions(
+  deps: SessionStateQueryDeps,
+  now = Date.now(),
+): void {
+  for (const [chatId, session] of [...deps.claudeSessions.entries()]) {
+    if (!isClaudeSessionIdle(deps, chatId, session, now)) continue
+    deps.closeClaudeSession(chatId, session)
+    deps.emitStateChange(chatId)
+  }
+}

package/src/server/claude-session-state.ts

@@ -0,0 +1,104 @@
+/**
+ * Core session and turn state types shared between AgentCoordinator (agent.ts)
+ * and the extracted runClaudeSession event-loop (claude-session-runner.ts).
+ *
+ * Keeping these in a dedicated module avoids a circular import: agent.ts imports
+ * values from claude-session-runner.ts, so claude-session-runner.ts must not
+ * import values from agent.ts. Both sides import these type-only definitions
+ * from this neutral file instead.
+ */
+import type { AgentProvider, KannaStatus, NormalizedToolCall, SlashCommand } from "../shared/types"
+import type { AnyValue } from "../shared/errors"
+import type { ClaudeSessionHandle, HarnessTurn } from "./harness-types"
+
+export interface PendingToolRequest {
+  toolUseId: string
+  tool: NormalizedToolCall & { toolKind: "ask_user_question" | "exit_plan_mode" }
+  resolve: (result: AnyValue) => void
+}
+
+export interface ActiveTurn {
+  chatId: string
+  provider: AgentProvider
+  turn: HarnessTurn
+  claudePromptSeq?: number
+  model: string
+  effort?: string
+  serviceTier?: "fast"
+  planMode: boolean
+  status: KannaStatus
+  pendingTool: PendingToolRequest | null
+  postToolFollowUp: { content: string; planMode: boolean } | null
+  hasFinalResult: boolean
+  cancelRequested: boolean
+  cancelRecorded: boolean
+  clientTraceId?: string
+  profilingStartedAt?: number
+  waitStartedAt: number | null
+  // True when this turn was synthesised by Kanna to inject `/compact` before
+  // the user's real message. Used to update the per-chat compact circuit
+  // breaker on completion (reset on success, increment on failure).
+  proactiveCompactInjection?: boolean
+  // _id of the user_prompt entry that triggered this turn (when appended on
+  // this turn). Used to attribute main-Claude-initiated subagent runs to the
+  // originating user message.
+  userMessageId: string | null
+}
+
+export interface ClaudeSessionState {
+  id: string
+  chatId: string
+  session: ClaudeSessionHandle
+  localPath: string
+  additionalDirectories: string[]
+  model: string
+  effort?: string
+  planMode: boolean
+  sessionToken: string | null
+  accountInfoLoaded: boolean
+  nextPromptSeq: number
+  pendingPromptSeqs: number[]
+  activeTokenId: string | null
+  oauthKeyMasked: string | null
+  oauthLabel: string | null
+  // OpenRouter turns route through the SDK with ANTHROPIC_AUTH_TOKEN set to the
+  // OpenRouter key, so the SDK self-reports a misleading Anthropic source. Hold
+  // the OpenRouter identity here to surface it in the account_info entry.
+  openrouterKeyMasked: string | null
+  openrouterModel: string | null
+  lastUsedAt: number
+  // Claude-Code background Bash tasks (`Bash(run_in_background: true)`) run as
+  // children of this PTY process and notify completion via a `<task-notification>`
+  // transcript line that the continuous tail re-enters as a real turn — but ONLY
+  // if the process is still alive. Track launched task ids + a keep-alive
+  // deadline so the idle reaper / budget enforcer does not tear the process down
+  // mid-flight. See adr-20260604-pty-background-task-keepalive.
+  backgroundTaskIds: Set<string>
+  backgroundTaskDeadlineAt: number
+  // Armed-loop state captured at spawn. Both drivers bake the loop tool-block
+  // into the spawn (PTY: --disallowedTools CLI args; SDK: options.disallowedTools
+  // so the model never sees the blocked tools — Claude Code's filter-at-spawn
+  // pattern). When the armed state changes (setup_loop arms / stop_loop or
+  // user-send disarms) the session must be respawned at the next turn boundary
+  // or the block goes stale.
+  loopArmedAtSpawn: boolean
+  /** SDK only: set once the workflows dir has been registered for this session. */
+  workflowsDirRegistered?: boolean
+  // Number of cancelled turns awaiting their interrupt-induced tail `result`.
+  // The SDK's `interrupt()` resolves the query loop with a `result` whose
+  // subtype is `error_during_execution` (NOT `cancelled`) and empty text, which
+  // would otherwise render as "An unknown error occurred." after the
+  // `interrupted` entry. Set on cancel, consumed (and the tail suppressed) when
+  // that result arrives, reset on each new turn so a no-tail cancel can't leak
+  // suppression onto a later real error.
+  cancelledResultPending: number
+  // Set by clearClaudeSessionContext (/clear machinery: setup_loop, background
+  // delivery). Once the chat's context is declared cleared, any session_token
+  // this in-flight session still emits belongs to the OLD conversation and
+  // must never re-persist over the wipe. Fresh spawns start unsuppressed.
+  suppressSessionTokenPersist: boolean
+}
+
+// Re-export SlashCommand as a convenience so importers of this module can get
+// the type without adding a separate shared/types import.
+export type { SlashCommand }

package/src/server/claude-slash-commands.test.ts

@@ -0,0 +1,277 @@
+/**
+ * Tests for claude-slash-commands.ts
+ *
+ * Covers the extracted ensureSlashCommandsLoaded and mergeLocalCatalog helpers.
+ * All IO is injected through the deps interface; no real sessions are spawned.
+ */
+
+import { describe, test, expect } from "bun:test"
+import { ensureSlashCommandsLoaded, mergeLocalCatalog, type SlashCommandsDeps } from "./claude-slash-commands"
+import type { SlashCommand } from "../shared/types"
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeSlashCommand(name: string, description = ""): SlashCommand {
+  return { name, description, argumentHint: "" }
+}
+
+function makeDeps(overrides: Partial<SlashCommandsDeps> = {}): SlashCommandsDeps {
+  return {
+    store: {
+      getChat: () => ({
+        provider: "claude" as const,
+        slashCommands: null,
+        planMode: false,
+        projectId: "proj-1",
+        sessionTokensByProvider: { claude: null },
+      }),
+      getProject: () => ({ id: "proj-1", localPath: "/tmp/proj" }),
+      recordSessionCommandsLoaded: async () => undefined,
+    },
+    claudeSessions: { get: () => undefined },
+    oauthPool: null,
+    slashCommandsInFlight: new Set<string>(),
+    emitStateChange: () => undefined,
+    resolveClaudeDriverPreference: () => "sdk",
+    startClaudeSessionPTY: async () => {
+      throw new Error("PTY not expected in these tests")
+    },
+    startClaudeSessionSDK: async () => {
+      throw new Error("SDK session not expected in these tests")
+    },
+    getSubagents: () => [],
+    getGlobalPromptAppend: () => undefined,
+    getEnabledCustomMcpServers: () => [],
+    claudePtyRegistry: null,
+    ptyInstanceRegistry: null,
+    workflowRegistry: null,
+    subagentTranscriptRegistry: null,
+    localCatalog: null,
+    ...overrides,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// mergeLocalCatalog
+// ---------------------------------------------------------------------------
+
+describe("mergeLocalCatalog", () => {
+  test("returns commands unchanged when localCatalog is null", () => {
+    const commands = [makeSlashCommand("foo"), makeSlashCommand("bar")]
+    const deps = makeDeps({ localCatalog: null })
+    const result = mergeLocalCatalog(deps, commands, "/cwd")
+    expect(result).toEqual(commands)
+  })
+
+  test("appends local commands that do not conflict with CLI commands", () => {
+    const cliCommands = [makeSlashCommand("help")]
+    const localCommands = [makeSlashCommand("mylocal")]
+    const deps = makeDeps({
+      localCatalog: { list: () => localCommands },
+    })
+    const result = mergeLocalCatalog(deps, cliCommands, "/cwd")
+    expect(result).toHaveLength(2)
+    expect(result[0]?.name).toBe("help")
+    expect(result[1]?.name).toBe("mylocal")
+  })
+
+  test("filters out local commands that duplicate CLI commands (case-insensitive)", () => {
+    const cliCommands = [makeSlashCommand("Help")]
+    const localCommands = [makeSlashCommand("help"), makeSlashCommand("custom")]
+    const deps = makeDeps({
+      localCatalog: { list: () => localCommands },
+    })
+    const result = mergeLocalCatalog(deps, cliCommands, "/cwd")
+    expect(result).toHaveLength(2)
+    expect(result.map((c) => c.name)).toEqual(["Help", "custom"])
+  })
+
+  test("returns commands unchanged when localCatalog.list throws", () => {
+    const cliCommands = [makeSlashCommand("foo")]
+    const deps = makeDeps({
+      localCatalog: {
+        list: () => {
+          throw new Error("scan failed")
+        },
+      },
+    })
+    const result = mergeLocalCatalog(deps, cliCommands, "/cwd")
+    expect(result).toEqual(cliCommands)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ensureSlashCommandsLoaded
+// ---------------------------------------------------------------------------
+
+describe("ensureSlashCommandsLoaded", () => {
+  test("returns early when chat is not found", async () => {
+    const deps = makeDeps({ store: { ...makeDeps().store, getChat: () => null } })
+    await expect(ensureSlashCommandsLoaded(deps, "chat-1")).resolves.toBeUndefined()
+  })
+
+  test("returns early for codex provider", async () => {
+    const deps = makeDeps({
+      store: {
+        ...makeDeps().store,
+        getChat: () => ({
+          provider: "codex" as const,
+          slashCommands: null,
+          planMode: false,
+          projectId: "proj-1",
+          sessionTokensByProvider: {},
+        }),
+      },
+    })
+    await expect(ensureSlashCommandsLoaded(deps, "chat-1")).resolves.toBeUndefined()
+  })
+
+  test("returns early when slash commands are already loaded", async () => {
+    const deps = makeDeps({
+      store: {
+        ...makeDeps().store,
+        getChat: () => ({
+          provider: "claude" as const,
+          slashCommands: [makeSlashCommand("help")],
+          planMode: false,
+          projectId: "proj-1",
+          sessionTokensByProvider: { claude: null },
+        }),
+      },
+    })
+    await expect(ensureSlashCommandsLoaded(deps, "chat-1")).resolves.toBeUndefined()
+  })
+
+  test("returns early when load is already in-flight", async () => {
+    const inFlight = new Set(["chat-1"])
+    const deps = makeDeps({ slashCommandsInFlight: inFlight })
+    await expect(ensureSlashCommandsLoaded(deps, "chat-1")).resolves.toBeUndefined()
+  })
+
+  test("loads commands from existing session and persists them", async () => {
+    const commands = [makeSlashCommand("clear"), makeSlashCommand("help")]
+    let recorded: SlashCommand[] = []
+    const deps = makeDeps({
+      claudeSessions: {
+        get: () => ({
+          session: { getSupportedCommands: async () => commands },
+        }),
+      },
+      store: {
+        getChat: () => ({
+          provider: "claude" as const,
+          slashCommands: null,
+          planMode: false,
+          projectId: "proj-1",
+          sessionTokensByProvider: { claude: null },
+        }),
+        getProject: () => ({ id: "proj-1", localPath: "/tmp/proj" }),
+        recordSessionCommandsLoaded: async (_chatId, cmds) => {
+          recorded = cmds
+        },
+      },
+    })
+    await ensureSlashCommandsLoaded(deps, "chat-1")
+    expect(recorded).toEqual(commands)
+    expect(deps.slashCommandsInFlight.has("chat-1")).toBe(false)
+  })
+
+  test("clears in-flight flag on error from existing session", async () => {
+    const deps = makeDeps({
+      claudeSessions: {
+        get: () => ({
+          session: {
+            getSupportedCommands: async () => {
+              throw new Error("session died")
+            },
+          },
+        }),
+      },
+    })
+    await ensureSlashCommandsLoaded(deps, "chat-1")
+    expect(deps.slashCommandsInFlight.has("chat-1")).toBe(false)
+  })
+
+  test("spawns ephemeral SDK session when no active session and no oauthPool", async () => {
+    const cliCommands = [makeSlashCommand("help")]
+    const closed = { value: false }
+    let recorded: SlashCommand[] = []
+    const noopAsync = async () => undefined
+    const deps = makeDeps({
+      startClaudeSessionSDK: async () => ({
+        provider: "claude" as const,
+        stream: (async function* () {})(),
+        interrupt: noopAsync,
+        close: () => { closed.value = true },
+        sendPrompt: noopAsync,
+        setModel: noopAsync,
+        setPermissionMode: noopAsync,
+        getSupportedCommands: async () => cliCommands,
+      }),
+      store: {
+        getChat: () => ({
+          provider: "claude" as const,
+          slashCommands: null,
+          planMode: false,
+          projectId: "proj-1",
+          sessionTokensByProvider: { claude: null },
+        }),
+        getProject: () => ({ id: "proj-1", localPath: "/tmp/proj" }),
+        recordSessionCommandsLoaded: async (_chatId, cmds) => {
+          recorded = cmds
+        },
+      },
+    })
+    await ensureSlashCommandsLoaded(deps, "chat-1")
+    expect(closed.value).toBe(true)
+    expect(recorded).toEqual(cliCommands)
+    expect(deps.slashCommandsInFlight.has("chat-1")).toBe(false)
+  })
+
+  test("merges local catalog commands into loaded commands", async () => {
+    const cliCommands = [makeSlashCommand("help")]
+    const localCommands = [makeSlashCommand("mylocal")]
+    let recorded: SlashCommand[] = []
+    const deps = makeDeps({
+      claudeSessions: {
+        get: () => ({
+          session: { getSupportedCommands: async () => cliCommands },
+        }),
+      },
+      localCatalog: { list: () => localCommands },
+      store: {
+        getChat: () => ({
+          provider: "claude" as const,
+          slashCommands: null,
+          planMode: false,
+          projectId: "proj-1",
+          sessionTokensByProvider: { claude: null },
+        }),
+        getProject: () => ({ id: "proj-1", localPath: "/tmp/proj" }),
+        recordSessionCommandsLoaded: async (_chatId, cmds) => {
+          recorded = cmds
+        },
+      },
+    })
+    await ensureSlashCommandsLoaded(deps, "chat-1")
+    expect(recorded).toHaveLength(2)
+    expect(recorded.map((c) => c.name)).toEqual(["help", "mylocal"])
+  })
+
+  test("skips ephemeral spawn when oauthPool has tokens but pickEphemeral returns null", async () => {
+    const deps = makeDeps({
+      oauthPool: {
+        pickEphemeral: () => null,
+        hasAnyToken: () => true,
+        markUsed: () => undefined,
+      },
+      startClaudeSessionSDK: async () => {
+        throw new Error("should not be called")
+      },
+    })
+    await expect(ensureSlashCommandsLoaded(deps, "chat-1")).resolves.toBeUndefined()
+    expect(deps.slashCommandsInFlight.has("chat-1")).toBe(false)
+  })
+})