@cuongtran001/kanna 1.2.0 → 1.3.1

package/src/server/event-store-helpers.ts

@@ -0,0 +1,235 @@
+/**
+ * Pure helper functions extracted from event-store.ts.
+ * No EventStore class dependencies. No IO side effects.
+ */
+import { log } from "../shared/log"
+import type { ChatHistorySnapshot, SlashCommand, TranscriptEntry } from "../shared/types"
+import { cloneTranscriptEntries } from "./events"
+import type { StoreEvent } from "./events"
+
+export interface TranscriptPageResult {
+  entries: TranscriptEntry[]
+  hasOlder: boolean
+  olderCursor: string | null
+}
+
+export function normalizeSidebarProjectOrder<T>(value: T): string[] {
+  if (!Array.isArray(value)) {
+    return []
+  }
+
+  const seen = new Set<string>()
+  const projectIds: string[] = []
+  for (const entry of value) {
+    if (typeof entry !== "string") continue
+    const projectId = entry.trim()
+    if (!projectId || seen.has(projectId)) continue
+    seen.add(projectId)
+    projectIds.push(projectId)
+  }
+
+  return projectIds
+}
+
+export function isSendToStartingProfilingEnabled(): boolean {
+  return process.env.KANNA_PROFILE_SEND_TO_STARTING === "1"
+}
+
+export function logSendToStartingProfile(stage: string, details?: Record<string, unknown>): void {
+  if (!isSendToStartingProfilingEnabled()) {
+    return
+  }
+
+  log.info("[kanna/send->starting][server]", JSON.stringify({
+    stage,
+    ...details,
+  }))
+}
+
+export function getReplayEventPriority(event: StoreEvent): number {
+  const discriminator = "type" in event ? event.type : event.kind
+  switch (discriminator) {
+    case "project_opened":
+    case "project_removed":
+    case "sidebar_project_order_set":
+    case "project_star_set":
+      return 0
+    case "chat_created":
+      return 1
+    case "chat_renamed":
+    case "chat_provider_set":
+    case "chat_plan_mode_set":
+      return 2
+    case "message_appended":
+      return 3
+    case "queued_message_enqueued":
+    case "queued_message_removed":
+      return 4
+    case "turn_started":
+      return 5
+    case "session_token_set":
+    case "session_commands_loaded":
+      return 6
+    case "pending_fork_session_token_set":
+      return 6
+    case "turn_cancelled":
+      return 7
+    case "turn_finished":
+    case "turn_failed":
+      return 8
+    case "chat_read_state_set":
+    case "chat_source_hash_set":
+    case "chat_policy_override_set":
+    case "chat_compact_failures_set":
+      return 9
+    case "chat_deleted":
+    case "chat_archived":
+    case "chat_unarchived":
+      return 10
+    case "auto_continue_proposed":
+    case "auto_continue_accepted":
+    case "auto_continue_rescheduled":
+    case "auto_continue_cancelled":
+    case "auto_continue_fired":
+    case "loop_armed":
+    case "loop_disarmed":
+      return 11
+    case "stack_added":
+    case "stack_removed":
+    case "stack_renamed":
+    case "stack_project_added":
+    case "stack_project_removed":
+      return 0
+    case "subagent_run_started":
+    case "subagent_message_delta":
+    case "subagent_entry_appended":
+    case "subagent_run_completed":
+    case "subagent_run_failed":
+    case "subagent_run_cancelled":
+    case "subagent_tool_pending":
+    case "subagent_tool_resolved":
+      return 5
+    // tool_request_put shares priority 5 with subagent_* events; sourceIndex
+    // tie-break orders them (tool-requests has sourceIndex 7, turns has 5).
+    case "tool_request_put":
+      return 5
+    case "tool_request_resolved":
+      return 6
+    case "orch_run_created":
+    case "orch_worktree_provisioned":
+    case "orch_worktree_init_started":
+    case "orch_worktree_init_completed":
+    case "orch_task_claimed":
+    case "orch_phase_started":
+    case "orch_phase_completed":
+    case "orch_gate_opened":
+    case "orch_gate_resolved":
+    case "orch_scope_overlap_flagged":
+    case "orch_config_warning":
+    case "orch_verify_started":
+    case "orch_verify_completed":
+    case "orch_task_committed":
+    case "orch_task_failed":
+    case "orch_task_requeued":
+    case "orch_run_completed":
+    case "orch_run_cancelled":
+      return 5
+    default: {
+      const _exhaustive: never = discriminator
+      throw new Error(`Unhandled replay event type: ${String(_exhaustive)}`)
+    }
+  }
+}
+
+export function encodeHistoryCursor(index: number): string {
+  return `idx:${index}`
+}
+
+export function decodeCursor(cursor: string): number {
+  if (cursor.startsWith("idx:")) {
+    const value = Number.parseInt(cursor.slice("idx:".length), 10)
+    if (!Number.isInteger(value) || value < 0) {
+      throw new Error("Invalid history cursor")
+    }
+    return value
+  }
+
+  throw new Error("Invalid history cursor")
+}
+
+export function slashCommandsEqual(a: SlashCommand[], b: SlashCommand[]): boolean {
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i += 1) {
+    const ai = a[i]
+    const bi = b[i]
+    if (ai.name !== bi.name || ai.description !== bi.description || ai.argumentHint !== bi.argumentHint) {
+      return false
+    }
+  }
+  return true
+}
+
+// `context_window_updated` entries are token-readout noise emitted once per
+// stream tick — only the latest value matters. A single turn can emit hundreds
+// of them, and the bounded live window (getMessagesPageFromEntries) counts each
+// 1:1 against the limit, so a flood evicts real turns (e.g. the user_prompt)
+// out of the snapshot the client renders. Collapsing each maximal run of
+// consecutive cwu entries to its last entry keeps the latest readout while
+// freeing window budget for real turns. Applied only on the live-window read
+// path (not getMessages), so getLatestContextWindowUsage / full-transcript
+// export / importer still observe every persisted cwu.
+export function coalesceContextWindowUpdates(entries: TranscriptEntry[]): TranscriptEntry[] {
+  const result: TranscriptEntry[] = []
+  for (let index = 0; index < entries.length; index += 1) {
+    const entry = entries[index]!
+    const next = entries[index + 1]
+    if (entry.kind === "context_window_updated" && next?.kind === "context_window_updated") {
+      // Drop this cwu; the last of the run survives.
+      continue
+    }
+    result.push(entry)
+  }
+  return result
+}
+
+export function getHistorySnapshot(page: TranscriptPageResult, recentLimit: number): ChatHistorySnapshot {
+  return {
+    hasOlder: page.hasOlder,
+    olderCursor: page.olderCursor,
+    recentLimit,
+  }
+}
+
+export function getForkedChatTitle(title: string): string {
+  const trimmed = title.trim()
+  if (!trimmed) return "Fork: New Chat"
+  return trimmed.startsWith("Fork: ") ? trimmed : `Fork: ${trimmed}`
+}
+
+/**
+ * Slice a page of transcript entries from a flat array.
+ *
+ * - `limit` controls page size; `beforeIndex` (from a cursor) is the
+ *   exclusive upper bound of the window (undefined = latest page).
+ * - Returns stable `TranscriptPageResult` with cloned entries so
+ *   callers cannot mutate the in-memory transcript.
+ */
+export function getMessagesPageFromEntries(
+  entries: TranscriptEntry[],
+  limit: number,
+  beforeIndex?: number,
+): TranscriptPageResult {
+  if (entries.length === 0) {
+    return { entries: [], hasOlder: false, olderCursor: null }
+  }
+  const endIndex =
+    beforeIndex === undefined
+      ? entries.length
+      : Math.max(0, Math.min(beforeIndex, entries.length))
+  const startIndex = Math.max(0, endIndex - limit)
+  return {
+    entries: cloneTranscriptEntries(entries.slice(startIndex, endIndex)),
+    hasOlder: startIndex > 0,
+    olderCursor: startIndex > 0 ? encodeHistoryCursor(startIndex) : null,
+  }
+}

package/src/server/event-store-init.ts

@@ -0,0 +1,276 @@
+/**
+ * EventStore initialization and snapshot/migration helpers extracted from
+ * event-store.ts.
+ *
+ * Contains initialize, ensureFile, clearStorage, loadSnapshot, resetState,
+ * clearLegacyTranscriptState, loadSidebarProjectOrder, replayLogs,
+ * shouldSnapshotLogs, snapshotAndTruncateLogs, getLegacyTranscriptStats,
+ * hasLegacyTranscriptData, and migrateLegacyTranscripts.
+ *
+ * This file does direct disk IO and must be suffixed .ts (not .adapter.ts)
+ * because the side-effect seal only applies to files in src/server/** production
+ * code that are NOT in an exempt glob. However, since this file performs IO and
+ * is NOT an adapter, callers (EventStore) must be careful to only call these
+ * from the class constructor / initialize flow.
+ *
+ * Must NOT import from event-store.ts (no circular deps).
+ */
+import path from "node:path"
+import type { AgentProvider, TranscriptEntry } from "../shared/types"
+import type { StoreState } from "./events"
+import type { StorageBackend } from "./storage/backend"
+import type { CachedTranscriptRef } from "./event-store-messages.adapter"
+import type { CloudflareTunnelEvent } from "./cloudflare-tunnel/events"
+import {
+  buildSnapshotFile,
+  calcShouldTruncateLogs,
+  computeLegacyTranscriptStats,
+  loadAndReplayLogs,
+  loadSidebarOrder,
+  loadSnapshotIntoState,
+  migrateLegacyTranscripts as migrateLegacyTranscriptsImpl,
+  truncateLogsAfterSnapshot,
+  type LegacyTranscriptStats,
+  type SnapshotLogPaths,
+} from "./event-store-snapshot"
+
+export type { LegacyTranscriptStats }
+
+// ─── Deps interface ────────────────────────────────────────────────────────
+
+export interface EventStoreInitDeps {
+  readonly storage: StorageBackend
+  readonly dataDir: string
+  readonly snapshotPath: string
+  readonly projectsLogPath: string
+  readonly chatsLogPath: string
+  readonly messagesLogPath: string
+  readonly queuedMessagesLogPath: string
+  readonly turnsLogPath: string
+  readonly schedulesLogPath: string
+  readonly tunnelLogPath: string
+  readonly sharesLogPath: string
+  readonly pushLogPath: string
+  readonly stacksLogPath: string
+  readonly toolRequestsLogPath: string
+  readonly orchLogPath: string
+  readonly transcriptsDir: string
+  readonly sidebarProjectOrderPath: string
+  readonly state: StoreState
+  readonly legacyMessagesByChatId: Map<string, TranscriptEntry[]>
+  readonly tunnelEventsByChatId: Map<string, CloudflareTunnelEvent[]>
+  readonly cachedTranscriptRef: CachedTranscriptRef
+  readonly sidebarProjectOrderRef: { value: string[] }
+  /** Gets the current legacySidebarProjectOrder array reference. */
+  getLegacySidebarProjectOrder: () => string[]
+  /** Sets legacySidebarProjectOrder. */
+  setLegacySidebarProjectOrder: (v: string[]) => void
+  /** Gets the current snapshotHasLegacyMessages value. */
+  getSnapshotHasLegacyMessages: () => boolean
+  /** Sets snapshotHasLegacyMessages. */
+  setSnapshotHasLegacyMessages: (v: boolean) => void
+  /** Gets the current storageReset flag. */
+  getStorageReset: () => boolean
+  /** Sets the storageReset flag. */
+  setStorageReset: (v: boolean) => void
+  /** The replayChatProvider map for log replay. */
+  replayChatProvider: Map<string, AgentProvider | null>
+  /** Applies a store event (routes to applyStoreEvent). */
+  applyEvent: (event: Parameters<typeof import("./event-store-apply").applyStoreEvent>[0]) => void
+}
+
+// ─── Internal helpers ──────────────────────────────────────────────────────
+
+function getLogPaths(deps: EventStoreInitDeps): SnapshotLogPaths {
+  return {
+    snapshotPath: deps.snapshotPath,
+    projectsLogPath: deps.projectsLogPath,
+    chatsLogPath: deps.chatsLogPath,
+    messagesLogPath: deps.messagesLogPath,
+    queuedMessagesLogPath: deps.queuedMessagesLogPath,
+    turnsLogPath: deps.turnsLogPath,
+    schedulesLogPath: deps.schedulesLogPath,
+    stacksLogPath: deps.stacksLogPath,
+    toolRequestsLogPath: deps.toolRequestsLogPath,
+    orchLogPath: deps.orchLogPath,
+  }
+}
+
+async function ensureFile(deps: EventStoreInitDeps, filePath: string): Promise<void> {
+  if (!(await deps.storage.exists(filePath))) {
+    await deps.storage.writeText(filePath, "")
+  }
+}
+
+function resetState(deps: EventStoreInitDeps): void {
+  deps.state.projectsById.clear()
+  deps.state.projectIdsByPath.clear()
+  deps.state.chatsById.clear()
+  deps.state.queuedMessagesByChatId.clear()
+  deps.state.sidebarProjectOrder = []
+  deps.state.autoContinueEventsByChatId.clear()
+  deps.state.stacksById.clear()
+  deps.tunnelEventsByChatId.clear()
+  deps.sidebarProjectOrderRef.value = []
+  deps.setLegacySidebarProjectOrder([])
+  deps.cachedTranscriptRef.value = null
+}
+
+function clearLegacyTranscriptState(deps: EventStoreInitDeps): void {
+  deps.legacyMessagesByChatId.clear()
+  deps.setSnapshotHasLegacyMessages(false)
+}
+
+export async function clearStorage(deps: EventStoreInitDeps): Promise<void> {
+  if (deps.getStorageReset()) return
+  deps.setStorageReset(true)
+  resetState(deps)
+  clearLegacyTranscriptState(deps)
+  await Promise.all([
+    deps.storage.writeText(deps.snapshotPath, ""),
+    deps.storage.writeText(deps.projectsLogPath, ""),
+    deps.storage.writeText(deps.chatsLogPath, ""),
+    deps.storage.writeText(deps.messagesLogPath, ""),
+    deps.storage.writeText(deps.queuedMessagesLogPath, ""),
+    deps.storage.writeText(deps.turnsLogPath, ""),
+    deps.storage.writeText(deps.schedulesLogPath, ""),
+    deps.storage.writeText(deps.tunnelLogPath, ""),
+    deps.storage.writeText(deps.sharesLogPath, ""),
+    deps.storage.writeText(deps.stacksLogPath, ""),
+    deps.storage.writeText(deps.toolRequestsLogPath, ""),
+    deps.storage.writeText(deps.orchLogPath, ""),
+  ])
+}
+
+async function loadSnapshot(deps: EventStoreInitDeps): Promise<void> {
+  const result = await loadSnapshotIntoState(
+    deps.storage,
+    deps.snapshotPath,
+    deps.state,
+    deps.legacyMessagesByChatId,
+    () => clearStorage(deps),
+  )
+  deps.setSnapshotHasLegacyMessages(result.snapshotHasLegacyMessages)
+  deps.setLegacySidebarProjectOrder(result.legacySidebarProjectOrder)
+}
+
+async function loadSidebarProjectOrder(deps: EventStoreInitDeps): Promise<void> {
+  deps.sidebarProjectOrderRef.value = await loadSidebarOrder(
+    deps.storage,
+    deps.sidebarProjectOrderPath,
+    deps.projectsLogPath,
+    deps.dataDir,
+    deps.getLegacySidebarProjectOrder(),
+  )
+}
+
+async function replayLogs(deps: EventStoreInitDeps): Promise<void> {
+  await loadAndReplayLogs(
+    deps.storage,
+    getLogPaths(deps),
+    () => deps.getStorageReset(),
+    (event) => { deps.applyEvent(event) },
+    () => clearStorage(deps),
+    () => { deps.replayChatProvider.clear() },
+  )
+}
+
+export async function shouldSnapshotLogs(deps: EventStoreInitDeps): Promise<boolean> {
+  return calcShouldTruncateLogs(deps.storage, getLogPaths(deps))
+}
+
+// ─── Public API ────────────────────────────────────────────────────────────
+
+export async function initializeEventStore(
+  deps: EventStoreInitDeps,
+  callbacks: {
+    loadTunnelEvents: () => Promise<void>
+    loadShareEvents: () => Promise<void>
+    hasLegacyTranscriptData: () => Promise<boolean>
+    snapshotAndTruncateLogs: () => Promise<void>
+  },
+): Promise<void> {
+  await deps.storage.mkdir(deps.dataDir)
+  await deps.storage.mkdir(deps.transcriptsDir)
+  await ensureFile(deps, deps.projectsLogPath)
+  await ensureFile(deps, deps.chatsLogPath)
+  await ensureFile(deps, deps.messagesLogPath)
+  await ensureFile(deps, deps.queuedMessagesLogPath)
+  await ensureFile(deps, deps.turnsLogPath)
+  await ensureFile(deps, deps.schedulesLogPath)
+  await ensureFile(deps, deps.tunnelLogPath)
+  await ensureFile(deps, deps.sharesLogPath)
+  await ensureFile(deps, deps.pushLogPath)
+  await ensureFile(deps, deps.stacksLogPath)
+  await ensureFile(deps, deps.toolRequestsLogPath)
+  await ensureFile(deps, deps.orchLogPath)
+  await loadSnapshot(deps)
+  await replayLogs(deps)
+  await callbacks.loadTunnelEvents()
+  await callbacks.loadShareEvents()
+  await loadSidebarProjectOrder(deps)
+  if (!(await callbacks.hasLegacyTranscriptData()) && await shouldSnapshotLogs(deps)) {
+    await callbacks.snapshotAndTruncateLogs()
+  }
+}
+
+export function resetEventStoreState(deps: EventStoreInitDeps): void {
+  resetState(deps)
+}
+
+export function clearEventStoreLegacyTranscriptState(deps: EventStoreInitDeps): void {
+  clearLegacyTranscriptState(deps)
+}
+
+// ─── Snapshot / legacy migration ops ─────────────────────────────────────────
+
+export async function getLegacyTranscriptStats(
+  deps: EventStoreInitDeps,
+): Promise<LegacyTranscriptStats> {
+  return computeLegacyTranscriptStats(
+    deps.storage,
+    deps.messagesLogPath,
+    deps.getSnapshotHasLegacyMessages(),
+    deps.legacyMessagesByChatId,
+  )
+}
+
+export async function hasLegacyTranscriptData(deps: EventStoreInitDeps): Promise<boolean> {
+  return (await getLegacyTranscriptStats(deps)).hasLegacyData
+}
+
+export async function snapshotAndTruncateLogs(deps: EventStoreInitDeps): Promise<void> {
+  const projects = [...deps.state.projectsById.values()].filter((p) => !p.deletedAt)
+  const snapshot = buildSnapshotFile(deps.state, projects)
+  const logPaths: SnapshotLogPaths = {
+    snapshotPath: deps.snapshotPath,
+    projectsLogPath: deps.projectsLogPath,
+    chatsLogPath: deps.chatsLogPath,
+    messagesLogPath: deps.messagesLogPath,
+    queuedMessagesLogPath: deps.queuedMessagesLogPath,
+    turnsLogPath: deps.turnsLogPath,
+    schedulesLogPath: deps.schedulesLogPath,
+    stacksLogPath: deps.stacksLogPath,
+    toolRequestsLogPath: deps.toolRequestsLogPath,
+    orchLogPath: deps.orchLogPath,
+  }
+  await truncateLogsAfterSnapshot(deps.storage, logPaths, JSON.stringify(snapshot, null, 2))
+}
+
+export async function migrateLegacyTranscripts(
+  deps: EventStoreInitDeps,
+  onProgress?: (message: string) => void,
+): Promise<boolean> {
+  const stats = await getLegacyTranscriptStats(deps)
+  return migrateLegacyTranscriptsImpl(
+    deps.storage,
+    deps.transcriptsDir,
+    stats,
+    deps.legacyMessagesByChatId,
+    (chatId) => path.join(deps.transcriptsDir, `${chatId}.jsonl`),
+    () => { clearEventStoreLegacyTranscriptState(deps) },
+    () => snapshotAndTruncateLogs(deps),
+    () => { deps.cachedTranscriptRef.value = null },
+    onProgress,
+  )
+}