@cuongtran001/kanna 1.3.0 → 1.3.1

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

@@ -0,0 +1,312 @@
+/**
+ * Orchestration read-model layer — pure functions that fold OrchestrationEvents
+ * into the `orchRunsById` map and project snapshots from it.
+ *
+ * Extracted from event-store.ts; EventStore delegates every orch* method here.
+ * All functions are pure with respect to IO: they mutate only the map they
+ * receive, which is the same Map instance held in StoreState.
+ */
+
+import { LOG_PREFIX } from "../shared/branding"
+import { log } from "../shared/log"
+import type { OrchRunSnapshot, OrchTaskSnapshot } from "../shared/orchestration-types"
+import type { OrchestrationEvent, OrchRunRecord, OrchTaskRecord } from "./events"
+import { isTaskEventType, nextRunStatus, nextTaskState } from "./orchestration-state-machine"
+
+// ---------------------------------------------------------------------------
+// Event application
+// ---------------------------------------------------------------------------
+
+/**
+ * Fold one OrchestrationEvent into the orchRunsById map in place.
+ * Mirrors the private `applyOrchestrationEvent` that lived in EventStore.
+ */
+export function applyOrchEvent(
+  orchRunsById: Map<string, OrchRunRecord>,
+  event: OrchestrationEvent,
+): void {
+  if (event.type === "orch_run_created") {
+    const tasksById = new Map<string, OrchTaskRecord>()
+    for (const spec of event.tasks) {
+      tasksById.set(spec.id, {
+        taskId: spec.id,
+        title: spec.title,
+        prompt: spec.prompt,
+        scopePaths: spec.scopePaths ?? [],
+        state: "queued",
+        ownerWorkerId: null,
+        worktreePath: null,
+        branch: null,
+        baseSha: null,
+        phaseIndex: -1,
+        attempts: 0,
+        error: null,
+        commitSha: null,
+        lastPhaseOutput: null,
+        verifying: false,
+        updatedAt: event.timestamp,
+      })
+    }
+    orchRunsById.set(event.runId, {
+      runId: event.runId,
+      status: "running",
+      config: event.config,
+      tasksById,
+      taskOrder: event.tasks.map((t) => t.id),
+      worktrees: [],
+      eventLog: [event],
+      createdAt: event.timestamp,
+      updatedAt: event.timestamp,
+    })
+    return
+  }
+
+  const run = orchRunsById.get(event.runId)
+  if (!run) return
+
+  run.eventLog.push(event)
+  run.updatedAt = event.timestamp
+
+  if (event.type === "orch_run_completed" || event.type === "orch_run_cancelled") {
+    const trans = nextRunStatus(run.status, event.type)
+    if (!trans.ok) {
+      log.warn(`${LOG_PREFIX} dropped illegal orch run transition`, {
+        runId: event.runId,
+        from: run.status,
+        event: event.type,
+      })
+      return
+    }
+    run.status = trans.next
+    return
+  }
+
+  if (event.type === "orch_scope_overlap_flagged") return // observability-only, no state fold
+  if (event.type === "orch_config_warning") return // observability-only, no state fold
+
+  // Worktree pool fold (F13)
+  if (event.type === "orch_worktree_provisioned") {
+    run.worktrees.push({
+      index: event.index,
+      path: event.path,
+      branch: event.branch,
+      heldByTaskId: null,
+      initialized: false,
+    })
+    return
+  }
+  if (event.type === "orch_worktree_init_started") return // timeline-only
+  if (event.type === "orch_worktree_init_completed") {
+    const slot = run.worktrees.find((w) => w.index === event.index)
+    if (slot) slot.initialized = event.ok
+    return
+  }
+
+  const task = run.tasksById.get(event.taskId)
+  if (!task) return
+
+  // FSM guard: drop an illegal task transition rather than corrupt the read
+  // model. The engine only emits legal transitions, so this is a defensive
+  // invariant (also protects replay of an older/foreign log).
+  if (isTaskEventType(event.type)) {
+    const trans = nextTaskState(task.state, event.type)
+    if (!trans.ok) {
+      log.warn(`${LOG_PREFIX} dropped illegal orch task transition`, {
+        runId: event.runId,
+        taskId: event.taskId,
+        from: task.state,
+        event: event.type,
+      })
+      return
+    }
+  }
+
+  task.updatedAt = event.timestamp
+  const slotOf = (t: OrchTaskRecord) => run.worktrees.find((w) => w.path === t.worktreePath)
+
+  switch (event.type) {
+    case "orch_task_claimed":
+      task.state = "claimed"
+      task.ownerWorkerId = event.workerId
+      task.worktreePath = event.worktreePath
+      task.branch = event.branch
+      task.baseSha = event.baseSha
+      task.attempts += 1
+      {
+        const slot = slotOf(task)
+        if (slot) slot.heldByTaskId = task.taskId
+      }
+      break
+    case "orch_phase_started":
+      task.state = "running"
+      task.phaseIndex = event.phaseIndex
+      task.verifying = false
+      break
+    case "orch_phase_completed":
+      task.lastPhaseOutput = event.output
+      break
+    case "orch_gate_opened":
+      task.state = "gated"
+      break
+    case "orch_gate_resolved":
+      if (event.decision === "approve") task.state = "running"
+      // reject: state stays gated; the engine appends orch_task_failed next
+      break
+    case "orch_verify_started":
+      task.verifying = true // observable stage; task stays "running"
+      break
+    case "orch_verify_completed":
+      task.verifying = false
+      break
+    case "orch_task_committed":
+      task.state = "committed"
+      task.ownerWorkerId = null
+      task.commitSha = event.commitSha
+      task.verifying = false
+      {
+        const slot = slotOf(task)
+        if (slot?.heldByTaskId === task.taskId) slot.heldByTaskId = null
+      }
+      break
+    case "orch_task_failed":
+      task.state = "failed"
+      task.ownerWorkerId = null
+      task.error = event.error
+      task.verifying = false
+      {
+        const slot = slotOf(task)
+        if (slot?.heldByTaskId === task.taskId) slot.heldByTaskId = null
+      }
+      break
+    case "orch_task_requeued":
+      // Slot hold deliberately KEPT (F13/F2): the task's uncommitted progress
+      // lives in its worktree — re-claim resumes the SAME slot.
+      task.state = "queued"
+      task.ownerWorkerId = null
+      task.verifying = false
+      break
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Snapshot projection
+// ---------------------------------------------------------------------------
+
+/** Project a stored OrchRunRecord into the wire-safe OrchRunSnapshot shape. */
+export function toOrchRunSnapshot(run: OrchRunRecord): OrchRunSnapshot {
+  const tasks: OrchTaskSnapshot[] = run.taskOrder.flatMap((taskId) => {
+    const t = run.tasksById.get(taskId)
+    if (!t) return []
+    return [
+      {
+        taskId: t.taskId,
+        title: t.title,
+        state: t.state,
+        ownerWorkerId: t.ownerWorkerId,
+        worktreePath: t.worktreePath,
+        branch: t.branch,
+        baseSha: t.baseSha,
+        phaseIndex: t.phaseIndex,
+        attempts: t.attempts,
+        error: t.error,
+        commitSha: t.commitSha,
+        verifying: t.verifying,
+        updatedAt: t.updatedAt,
+      },
+    ]
+  })
+  return {
+    runId: run.runId,
+    status: run.status,
+    config: run.config,
+    tasks,
+    worktrees: run.worktrees.map((w) => ({ ...w })),
+    createdAt: run.createdAt,
+    updatedAt: run.updatedAt,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Query helpers
+// ---------------------------------------------------------------------------
+
+/** Look up one run by id and project it to a snapshot. */
+export function getOrchRunSnapshot(
+  orchRunsById: Map<string, OrchRunRecord>,
+  runId: string,
+): OrchRunSnapshot | null {
+  const run = orchRunsById.get(runId)
+  if (!run) return null
+  return toOrchRunSnapshot(run)
+}
+
+/** Project all runs to snapshots. */
+export function getAllOrchRunSnapshots(
+  orchRunsById: Map<string, OrchRunRecord>,
+): OrchRunSnapshot[] {
+  return [...orchRunsById.values()].map(toOrchRunSnapshot)
+}
+
+/** Task spec lookup for the engine (records keep prompt/scope; snapshots do not). */
+export function getOrchTaskSpec(
+  orchRunsById: Map<string, OrchRunRecord>,
+  runId: string,
+  taskId: string,
+): { prompt: string; scopePaths: string[] } | null {
+  const task = orchRunsById.get(runId)?.tasksById.get(taskId)
+  if (!task) return null
+  return { prompt: task.prompt, scopePaths: task.scopePaths }
+}
+
+/** Last completed phase's output — {{PRIOR}} context when resuming a gated/recovered task. */
+export function getOrchLastPhaseOutput(
+  orchRunsById: Map<string, OrchRunRecord>,
+  runId: string,
+  taskId: string,
+): string | null {
+  return orchRunsById.get(runId)?.tasksById.get(taskId)?.lastPhaseOutput ?? null
+}
+
+/** Full ordered event timeline for one run — the rich drill-in source (F8). */
+export function getOrchRunEvents(
+  orchRunsById: Map<string, OrchRunRecord>,
+  runId: string,
+): OrchestrationEvent[] {
+  return [...(orchRunsById.get(runId)?.eventLog ?? [])]
+}
+
+// ---------------------------------------------------------------------------
+// Recovery iterators
+// ---------------------------------------------------------------------------
+
+/**
+ * Tasks a restart must RE-QUEUE.
+ * `gated` is deliberately excluded — a gated task is re-armed in place
+ * (gate re-notified), never requeued.
+ */
+export function* nonTerminalOrchTasks(
+  orchRunsById: Map<string, OrchRunRecord>,
+): Generator<{ runId: string; taskId: string; state: "claimed" | "running" }> {
+  for (const run of orchRunsById.values()) {
+    if (run.status !== "running") continue
+    for (const task of run.tasksById.values()) {
+      if (task.state === "claimed" || task.state === "running") {
+        yield { runId: run.runId, taskId: task.taskId, state: task.state }
+      }
+    }
+  }
+}
+
+/** Tasks paused at a hard gate — re-armed (not requeued) by recoverOnStartup. */
+export function* gatedOrchTasks(
+  orchRunsById: Map<string, OrchRunRecord>,
+): Generator<{ runId: string; taskId: string; phaseIndex: number }> {
+  for (const run of orchRunsById.values()) {
+    if (run.status !== "running") continue
+    for (const task of run.tasksById.values()) {
+      if (task.state === "gated") {
+        yield { runId: run.runId, taskId: task.taskId, phaseIndex: task.phaseIndex }
+      }
+    }
+  }
+}

package/src/server/event-store-peripheral-events.adapter.test.ts

@@ -0,0 +1,254 @@
+import { describe, expect, test } from "bun:test"
+import type { CloudflareTunnelEvent } from "./cloudflare-tunnel/events"
+import type { PushEvent } from "./push/events"
+import type { ShareEvent } from "./session-share/share-projection"
+import type { StorageBackend } from "./storage/backend"
+import {
+  appendPushEvent,
+  appendShareEvent,
+  appendTunnelEvent,
+  getShareEvents,
+  getTunnelEvents,
+  listTunnelChats,
+  loadPushEvents,
+  loadShareEvents,
+  loadTunnelEvents,
+  type PeripheralEventsDeps,
+} from "./event-store-peripheral-events.adapter"
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Minimal in-memory StorageBackend stub. */
+function makeStorage(files: Map<string, string> = new Map()): StorageBackend {
+  return {
+    mkdir: async () => {},
+    exists: async (p) => files.has(p),
+    existsSync: (p) => files.has(p),
+    size: async (p) => files.get(p)?.length ?? 0,
+    readText: async (p) => files.get(p) ?? "",
+    readTextSync: (p) => files.get(p) ?? "",
+    writeText: async (p, v) => { files.set(p, v) },
+    appendText: async (p, v) => { files.set(p, (files.get(p) ?? "") + v) },
+    rename: async () => {},
+    remove: async () => {},
+  }
+}
+
+function makeWriteChainRef() {
+  let chain = Promise.resolve()
+  return {
+    getWriteChain: () => chain,
+    setWriteChain: (p: Promise<void>) => { chain = p },
+  }
+}
+
+function makeDeps(overrides: Partial<PeripheralEventsDeps> = {}): PeripheralEventsDeps {
+  const wc = makeWriteChainRef()
+  return {
+    storage: makeStorage(),
+    tunnelLogPath: "/data/tunnels.jsonl",
+    sharesLogPath: "/data/shares.jsonl",
+    pushLogPath: "/data/push.jsonl",
+    tunnelEventsByChatId: new Map(),
+    shareEventsAll: [],
+    getWriteChain: wc.getWriteChain,
+    setWriteChain: wc.setWriteChain,
+    ...overrides,
+  }
+}
+
+function makeTunnelEvent(chatId = "chat-1"): CloudflareTunnelEvent {
+  return { type: "tunnel_started", chatId, tunnelId: "t-1", url: "https://ex.trycloudflare.com", timestamp: 1000 } as unknown as CloudflareTunnelEvent
+}
+
+function makeShareEvent(chatId = "chat-1"): ShareEvent {
+  return { type: "share_minted", chatId, shareId: "s-1", token: "tok", expiresAt: null, timestamp: 1000 } as unknown as ShareEvent
+}
+
+function makePushEvent(): PushEvent {
+  return { type: "push_device_registered", deviceId: "d-1", pushToken: "pt-1", platform: "web", timestamp: 1000 } as unknown as PushEvent
+}
+
+// ---------------------------------------------------------------------------
+// Tunnel tests
+// ---------------------------------------------------------------------------
+
+describe("getTunnelEvents", () => {
+  test("returns empty array for unknown chatId", () => {
+    const deps = makeDeps()
+    expect(getTunnelEvents(deps, "no-chat")).toEqual([])
+  })
+
+  test("returns list for known chatId", () => {
+    const ev = makeTunnelEvent("chat-a")
+    const tunnelEventsByChatId = new Map([["chat-a", [ev]]])
+    const deps = makeDeps({ tunnelEventsByChatId })
+    expect(getTunnelEvents(deps, "chat-a")).toEqual([ev])
+  })
+
+  test("returns a copy (not the original array)", () => {
+    const ev = makeTunnelEvent("chat-a")
+    const inner: CloudflareTunnelEvent[] = [ev]
+    const tunnelEventsByChatId = new Map([["chat-a", inner]])
+    const deps = makeDeps({ tunnelEventsByChatId })
+    const result = getTunnelEvents(deps, "chat-a")
+    expect(result).toEqual([ev])
+    expect(result).not.toBe(inner)
+  })
+})
+
+describe("listTunnelChats", () => {
+  test("returns empty array when no chats", () => {
+    const deps = makeDeps()
+    expect(listTunnelChats(deps)).toEqual([])
+  })
+
+  test("returns all chatIds with tunnel events", () => {
+    const tunnelEventsByChatId = new Map([
+      ["c1", [makeTunnelEvent("c1")]],
+      ["c2", [makeTunnelEvent("c2")]],
+    ])
+    const deps = makeDeps({ tunnelEventsByChatId })
+    expect(listTunnelChats(deps)).toEqual(expect.arrayContaining(["c1", "c2"]))
+  })
+})
+
+describe("appendTunnelEvent", () => {
+  test("writes to tunnelLogPath and updates in-memory map", async () => {
+    const files = new Map([[ "/data/tunnels.jsonl", "" ]])
+    const storage = makeStorage(files)
+    const deps = makeDeps({ storage })
+    const ev = makeTunnelEvent("chat-1")
+
+    await appendTunnelEvent(deps, ev)
+
+    // Disk
+    const content = files.get("/data/tunnels.jsonl") ?? ""
+    expect(content.trim()).toBe(JSON.stringify(ev))
+
+    // In-memory map
+    expect(getTunnelEvents(deps, "chat-1")).toEqual([ev])
+  })
+
+  test("chains multiple appends in order", async () => {
+    const files = new Map([["/data/tunnels.jsonl", ""]])
+    const storage = makeStorage(files)
+    const deps = makeDeps({ storage })
+    const ev1 = { ...makeTunnelEvent("chat-1"), tunnelId: "t-1" }
+    const ev2 = { ...makeTunnelEvent("chat-1"), tunnelId: "t-2" }
+
+    await Promise.all([appendTunnelEvent(deps, ev1), appendTunnelEvent(deps, ev2)])
+
+    const lines = (files.get("/data/tunnels.jsonl") ?? "").trim().split("\n")
+    expect(lines.length).toBe(2)
+    expect(JSON.parse(lines[0]!).tunnelId).toBe("t-1")
+    expect(JSON.parse(lines[1]!).tunnelId).toBe("t-2")
+  })
+})
+
+describe("loadTunnelEvents", () => {
+  test("populates in-memory map from disk", async () => {
+    const ev = makeTunnelEvent("chat-x")
+    const files = new Map([["/data/tunnels.jsonl", `${JSON.stringify(ev)}\n`]])
+    const storage = makeStorage(files)
+    const tunnelEventsByChatId = new Map<string, CloudflareTunnelEvent[]>()
+    const deps = makeDeps({ storage, tunnelEventsByChatId })
+
+    await loadTunnelEvents(deps)
+
+    expect(getTunnelEvents(deps, "chat-x")).toEqual([ev])
+  })
+
+  test("handles empty log file without errors", async () => {
+    const files = new Map([["/data/tunnels.jsonl", ""]])
+    const deps = makeDeps({ storage: makeStorage(files) })
+    await expect(loadTunnelEvents(deps)).resolves.toBeUndefined()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Share tests
+// ---------------------------------------------------------------------------
+
+describe("getShareEvents", () => {
+  test("returns empty array by default", () => {
+    const deps = makeDeps()
+    expect(getShareEvents(deps)).toEqual([])
+  })
+
+  test("returns a copy of shareEventsAll", () => {
+    const ev = makeShareEvent()
+    const shareEventsAll: ShareEvent[] = [ev]
+    const deps = makeDeps({ shareEventsAll })
+    const result = getShareEvents(deps)
+    expect(result).toEqual([ev])
+    expect(result).not.toBe(shareEventsAll)
+  })
+})
+
+describe("appendShareEvent", () => {
+  test("writes to sharesLogPath and pushes into shareEventsAll", async () => {
+    const files = new Map([["/data/shares.jsonl", ""]])
+    const storage = makeStorage(files)
+    const shareEventsAll: ShareEvent[] = []
+    const deps = makeDeps({ storage, shareEventsAll })
+    const ev = makeShareEvent("chat-2")
+
+    await appendShareEvent(deps, ev)
+
+    expect(files.get("/data/shares.jsonl")?.trim()).toBe(JSON.stringify(ev))
+    expect(shareEventsAll).toEqual([ev])
+  })
+})
+
+describe("loadShareEvents", () => {
+  test("fills shareEventsAll from disk", async () => {
+    const ev = makeShareEvent("chat-y")
+    const files = new Map([["/data/shares.jsonl", `${JSON.stringify(ev)}\n`]])
+    const storage = makeStorage(files)
+    const shareEventsAll: ShareEvent[] = []
+    const deps = makeDeps({ storage, shareEventsAll })
+
+    await loadShareEvents(deps)
+
+    expect(shareEventsAll).toEqual([ev])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Push tests
+// ---------------------------------------------------------------------------
+
+describe("appendPushEvent", () => {
+  test("writes to pushLogPath (no in-memory state)", async () => {
+    const files = new Map([["/data/push.jsonl", ""]])
+    const storage = makeStorage(files)
+    const deps = makeDeps({ storage })
+    const ev = makePushEvent()
+
+    await appendPushEvent(deps, ev)
+
+    expect(files.get("/data/push.jsonl")?.trim()).toBe(JSON.stringify(ev))
+  })
+})
+
+describe("loadPushEvents", () => {
+  test("returns events from push log", async () => {
+    const ev = makePushEvent()
+    const files = new Map([["/data/push.jsonl", `${JSON.stringify(ev)}\n`]])
+    const deps = makeDeps({ storage: makeStorage(files) })
+
+    const result = await loadPushEvents(deps)
+
+    expect(result).toEqual([ev])
+  })
+
+  test("returns empty array for empty log", async () => {
+    const files = new Map([["/data/push.jsonl", ""]])
+    const deps = makeDeps({ storage: makeStorage(files) })
+    const result = await loadPushEvents(deps)
+    expect(result).toEqual([])
+  })
+})

package/src/server/event-store-peripheral-events.adapter.ts

@@ -0,0 +1,105 @@
+/**
+ * Tunnel, Share, and Push peripheral event operations extracted from
+ * event-store.ts. All IO is performed through the injected StorageBackend.
+ *
+ * This module is an adapter (`.adapter.ts`) because it performs disk IO.
+ * It must NOT import from event-store.ts (no circular deps).
+ */
+import type { StorageBackend } from "./storage/backend"
+import type { CloudflareTunnelEvent } from "./cloudflare-tunnel/events"
+import type { PushEvent } from "./push/events"
+import type { ShareEvent } from "./session-share/share-projection"
+import {
+  applyTunnelEventToMap,
+  loadPushEventsFromLog,
+  loadShareEventsFromLog,
+  loadTunnelEventsFromLog,
+} from "./event-store-snapshot"
+
+// ─── Deps interface ────────────────────────────────────────────────────────
+
+export interface PeripheralEventsDeps {
+  readonly storage: StorageBackend
+  readonly tunnelLogPath: string
+  readonly sharesLogPath: string
+  readonly pushLogPath: string
+  readonly tunnelEventsByChatId: Map<string, CloudflareTunnelEvent[]>
+  /** Mutable share events array — methods push into this directly. */
+  readonly shareEventsAll: ShareEvent[]
+  /** Read the current write-chain promise. */
+  getWriteChain: () => Promise<void>
+  /** Replace the write-chain promise (called inside async chain links). */
+  setWriteChain: (p: Promise<void>) => void
+}
+
+// ─── Tunnel ────────────────────────────────────────────────────────────────
+
+export async function appendTunnelEvent(
+  deps: PeripheralEventsDeps,
+  event: CloudflareTunnelEvent,
+): Promise<void> {
+  const payload = `${JSON.stringify(event)}\n`
+  const chain = deps.getWriteChain().then(async () => {
+    await deps.storage.appendText(deps.tunnelLogPath, payload)
+    applyTunnelEventToMap(deps.tunnelEventsByChatId, event)
+  })
+  deps.setWriteChain(chain)
+  await chain
+}
+
+export function getTunnelEvents(
+  deps: PeripheralEventsDeps,
+  chatId: string,
+): CloudflareTunnelEvent[] {
+  const list = deps.tunnelEventsByChatId.get(chatId)
+  return list ? [...list] : []
+}
+
+export function listTunnelChats(deps: PeripheralEventsDeps): string[] {
+  return [...deps.tunnelEventsByChatId.keys()]
+}
+
+export async function loadTunnelEvents(deps: PeripheralEventsDeps): Promise<void> {
+  await loadTunnelEventsFromLog(deps.storage, deps.tunnelLogPath, deps.tunnelEventsByChatId)
+}
+
+// ─── Share ─────────────────────────────────────────────────────────────────
+
+export async function appendShareEvent(
+  deps: PeripheralEventsDeps,
+  event: ShareEvent,
+): Promise<void> {
+  const payload = `${JSON.stringify(event)}\n`
+  const chain = deps.getWriteChain().then(async () => {
+    await deps.storage.appendText(deps.sharesLogPath, payload)
+    deps.shareEventsAll.push(event)
+  })
+  deps.setWriteChain(chain)
+  await chain
+}
+
+export function getShareEvents(deps: PeripheralEventsDeps): ShareEvent[] {
+  return [...deps.shareEventsAll]
+}
+
+export async function loadShareEvents(deps: PeripheralEventsDeps): Promise<void> {
+  await loadShareEventsFromLog(deps.storage, deps.sharesLogPath, deps.shareEventsAll)
+}
+
+// ─── Push ──────────────────────────────────────────────────────────────────
+
+export async function appendPushEvent(
+  deps: PeripheralEventsDeps,
+  event: PushEvent,
+): Promise<void> {
+  const payload = `${JSON.stringify(event)}\n`
+  const chain = deps.getWriteChain().then(async () => {
+    await deps.storage.appendText(deps.pushLogPath, payload)
+  })
+  deps.setWriteChain(chain)
+  await chain
+}
+
+export async function loadPushEvents(deps: PeripheralEventsDeps): Promise<PushEvent[]> {
+  return loadPushEventsFromLog(deps.storage, deps.pushLogPath)
+}