@cuongtran001/kanna 1.3.0 → 1.4.0

package/src/server/ws-router-orch.test.ts

@@ -0,0 +1,190 @@
+import { describe, expect, mock, test } from "bun:test"
+import type { OrchCommandDeps, OrchAgentDep } from "./ws-router-orch"
+import { handleOrchCommand } from "./ws-router-orch"
+import type { ClientCommand } from "../shared/protocol"
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeAgent(overrides: Partial<OrchAgentDep> = {}): OrchAgentDep {
+  return {
+    runOrchestration: mock(async () => ({ ok: true as const, runId: "run-1" })),
+    cancelOrchRun: mock(async () => {}),
+    getOrchRunDetail: mock(() => null),
+    ...overrides,
+  }
+}
+
+function makeDeps(
+  agentOverrides?: Partial<OrchAgentDep>,
+  wfOverride?: OrchCommandDeps["workflowRegistry"],
+  saOverride?: OrchCommandDeps["subagentTranscriptRegistry"],
+): OrchCommandDeps & { sent: unknown[] } {
+  const sent: unknown[] = []
+  return {
+    agent: makeAgent(agentOverrides),
+    workflowRegistry: wfOverride,
+    subagentTranscriptRegistry: saOverride,
+    send: (envelope) => { sent.push(envelope) },
+    sent,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Unrecognized command
+// ---------------------------------------------------------------------------
+
+describe("handleOrchCommand", () => {
+  test("returns false for a non-orch command", async () => {
+    const deps = makeDeps()
+    const handled = await handleOrchCommand(
+      deps,
+      { type: "settings.readAppSettings" } as unknown as ClientCommand,
+      "r0",
+    )
+    expect(handled).toBe(false)
+    expect(deps.sent).toHaveLength(0)
+  })
+
+  // ---------------------------------------------------------------------------
+  // workflows.getRun
+  // ---------------------------------------------------------------------------
+
+  test("workflows.getRun — returns run from registry", async () => {
+    const run = { runId: "wf-1", taskId: "t-1", workflowName: "test" } as unknown as ReturnType<
+      NonNullable<OrchCommandDeps["workflowRegistry"]>["getRun"]
+    >
+    const wf: NonNullable<OrchCommandDeps["workflowRegistry"]> = {
+      getRun: mock(() => run),
+      getAgentTranscript: mock(() => []),
+    }
+    const deps = makeDeps(undefined, wf)
+    const handled = await handleOrchCommand(
+      deps,
+      { type: "workflows.getRun", chatId: "c-1", runId: "wf-1" },
+      "r1",
+    )
+    expect(handled).toBe(true)
+    expect(wf.getRun).toHaveBeenCalledWith("c-1", "wf-1")
+    expect(deps.sent).toHaveLength(1)
+    expect((deps.sent[0] as { result: unknown }).result).toBe(run)
+  })
+
+  test("workflows.getRun — returns null when registry absent", async () => {
+    const deps = makeDeps(undefined, undefined)
+    const handled = await handleOrchCommand(
+      deps,
+      { type: "workflows.getRun", chatId: "c-1", runId: "wf-1" },
+      "r2",
+    )
+    expect(handled).toBe(true)
+    expect((deps.sent[0] as { result: unknown }).result).toBeNull()
+  })
+
+  // ---------------------------------------------------------------------------
+  // workflows.getAgentTranscript
+  // ---------------------------------------------------------------------------
+
+  test("workflows.getAgentTranscript — returns entries", async () => {
+    const entries = [{ type: "assistant", content: "hi" }] as unknown as ReturnType<
+      NonNullable<OrchCommandDeps["workflowRegistry"]>["getAgentTranscript"]
+    >
+    const wf: NonNullable<OrchCommandDeps["workflowRegistry"]> = {
+      getRun: mock(() => null),
+      getAgentTranscript: mock(() => entries),
+    }
+    const deps = makeDeps(undefined, wf)
+    const handled = await handleOrchCommand(
+      deps,
+      { type: "workflows.getAgentTranscript", chatId: "c-1", runId: "wf-1", agentId: "ag-1" },
+      "r3",
+    )
+    expect(handled).toBe(true)
+    expect(wf.getAgentTranscript).toHaveBeenCalledWith("c-1", "wf-1", "ag-1")
+    expect((deps.sent[0] as { result: unknown }).result).toBe(entries)
+  })
+
+  // ---------------------------------------------------------------------------
+  // subagents.getRun
+  // ---------------------------------------------------------------------------
+
+  test("subagents.getRun — returns entries from transcript registry", async () => {
+    const entries = [{ type: "assistant", content: "hello" }] as unknown as ReturnType<
+      NonNullable<OrchCommandDeps["subagentTranscriptRegistry"]>["getAgentTranscript"]
+    >
+    const sa: NonNullable<OrchCommandDeps["subagentTranscriptRegistry"]> = {
+      getAgentTranscript: mock(() => entries),
+    }
+    const deps = makeDeps(undefined, undefined, sa)
+    const handled = await handleOrchCommand(
+      deps,
+      { type: "subagents.getRun", chatId: "c-1", agentId: "ag-2" },
+      "r4",
+    )
+    expect(handled).toBe(true)
+    expect(sa.getAgentTranscript).toHaveBeenCalledWith("c-1", "ag-2")
+    expect((deps.sent[0] as { result: unknown }).result).toBe(entries)
+  })
+
+  test("subagents.getRun — returns empty array when registry absent", async () => {
+    const deps = makeDeps(undefined, undefined, undefined)
+    const handled = await handleOrchCommand(
+      deps,
+      { type: "subagents.getRun", chatId: "c-1", agentId: "ag-2" },
+      "r5",
+    )
+    expect(handled).toBe(true)
+    expect((deps.sent[0] as { result: unknown }).result).toEqual([])
+  })
+
+  // ---------------------------------------------------------------------------
+  // orch.run
+  // ---------------------------------------------------------------------------
+
+  test("orch.run — delegates to agent.runOrchestration and acks with result", async () => {
+    const orchResult = { ok: true as const, runId: "run-42" }
+    const deps = makeDeps({ runOrchestration: mock(async () => orchResult) })
+    const handled = await handleOrchCommand(
+      deps,
+      { type: "orch.run", chatId: "c-1", input: { tasks: ["task A"] } },
+      "r6",
+    )
+    expect(handled).toBe(true)
+    expect(deps.agent.runOrchestration).toHaveBeenCalledWith("c-1", { tasks: ["task A"] })
+    expect((deps.sent[0] as { result: unknown }).result).toEqual(orchResult)
+  })
+
+  // ---------------------------------------------------------------------------
+  // orch.cancelRun
+  // ---------------------------------------------------------------------------
+
+  test("orch.cancelRun — delegates to agent.cancelOrchRun and acks ok", async () => {
+    const deps = makeDeps()
+    const handled = await handleOrchCommand(
+      deps,
+      { type: "orch.cancelRun", runId: "run-42" },
+      "r7",
+    )
+    expect(handled).toBe(true)
+    expect(deps.agent.cancelOrchRun).toHaveBeenCalledWith("run-42")
+    expect((deps.sent[0] as { result: unknown }).result).toEqual({ ok: true })
+  })
+
+  // ---------------------------------------------------------------------------
+  // orch.getRun
+  // ---------------------------------------------------------------------------
+
+  test("orch.getRun — delegates to agent.getOrchRunDetail and acks with detail", async () => {
+    const detail = { runId: "run-42", status: "running" } as unknown as ReturnType<OrchAgentDep["getOrchRunDetail"]>
+    const deps = makeDeps({ getOrchRunDetail: mock(() => detail) })
+    const handled = await handleOrchCommand(
+      deps,
+      { type: "orch.getRun", runId: "run-42" },
+      "r8",
+    )
+    expect(handled).toBe(true)
+    expect(deps.agent.getOrchRunDetail).toHaveBeenCalledWith("run-42")
+    expect((deps.sent[0] as { result: unknown }).result).toBe(detail)
+  })
+})

package/src/server/ws-router-orch.ts

@@ -0,0 +1,93 @@
+/**
+ * ws-router-orch.ts
+ *
+ * WS command handlers for orchestration, workflow observability, and
+ * subagent-transcript queries:
+ *   orch.run, orch.cancelRun, orch.getRun,
+ *   workflows.getRun, workflows.getAgentTranscript,
+ *   subagents.getRun
+ *
+ * Extracted from ws-router.ts.
+ */
+import { PROTOCOL_VERSION } from "../shared/types"
+import type { ClientCommand, ServerEnvelope } from "../shared/protocol"
+import type { OrchRunInput, OrchRunDetail } from "../shared/orchestration-types"
+import type { WorkflowRegistry } from "./workflow-registry"
+import type { SubagentTranscriptRegistry } from "./subagent-transcript-registry"
+
+// ---------------------------------------------------------------------------
+// Dep interface (duck-typed; avoids circular imports with ws-router.ts)
+// ---------------------------------------------------------------------------
+
+/** The subset of AgentCoordinator methods consumed by orch/workflow WS commands. */
+export interface OrchAgentDep {
+  runOrchestration(
+    chatId: string,
+    input: OrchRunInput,
+  ): Promise<{ ok: true; runId: string } | { ok: false; errors: string[] }>
+  cancelOrchRun(runId: string): Promise<void>
+  getOrchRunDetail(runId: string): OrchRunDetail | null
+}
+
+export interface OrchCommandDeps {
+  /** Orchestration methods from AgentCoordinator. */
+  agent: OrchAgentDep
+  /** Optional workflow registry (may be absent if not configured). */
+  workflowRegistry: Pick<WorkflowRegistry, "getRun" | "getAgentTranscript"> | undefined
+  /** Optional subagent transcript registry. */
+  subagentTranscriptRegistry: Pick<SubagentTranscriptRegistry, "getAgentTranscript"> | undefined
+  /** Pre-bound to the current WebSocket; called to send an ack envelope. */
+  send: (envelope: ServerEnvelope) => void
+}
+
+// ---------------------------------------------------------------------------
+// Command dispatcher
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle one orchestration/workflow/subagent-transcript WS command.
+ *
+ * Returns `true` when the command was handled (caller should `return`).
+ * Returns `false` when the command type is outside this module's scope.
+ */
+export async function handleOrchCommand(
+  deps: OrchCommandDeps,
+  command: ClientCommand,
+  id: string,
+): Promise<boolean> {
+  const { agent, workflowRegistry, subagentTranscriptRegistry, send } = deps
+
+  switch (command.type) {
+    case "workflows.getRun": {
+      const run = workflowRegistry?.getRun(command.chatId, command.runId) ?? null
+      send({ v: PROTOCOL_VERSION, type: "ack", id, result: run })
+      return true
+    }
+    case "workflows.getAgentTranscript": {
+      const entries = workflowRegistry?.getAgentTranscript(command.chatId, command.runId, command.agentId) ?? []
+      send({ v: PROTOCOL_VERSION, type: "ack", id, result: entries })
+      return true
+    }
+    case "subagents.getRun": {
+      const entries = subagentTranscriptRegistry?.getAgentTranscript(command.chatId, command.agentId) ?? []
+      send({ v: PROTOCOL_VERSION, type: "ack", id, result: entries })
+      return true
+    }
+    case "orch.run": {
+      const result = await agent.runOrchestration(command.chatId, command.input)
+      send({ v: PROTOCOL_VERSION, type: "ack", id, result })
+      return true
+    }
+    case "orch.cancelRun": {
+      await agent.cancelOrchRun(command.runId)
+      send({ v: PROTOCOL_VERSION, type: "ack", id, result: { ok: true } })
+      return true
+    }
+    case "orch.getRun": {
+      send({ v: PROTOCOL_VERSION, type: "ack", id, result: agent.getOrchRunDetail(command.runId) })
+      return true
+    }
+    default:
+      return false
+  }
+}

package/src/server/ws-router-project.test.ts

@@ -0,0 +1,403 @@
+/**
+ * ws-router-project.test.ts
+ *
+ * Unit tests for the project / session / sidebar / system / update WS command handlers.
+ */
+import { describe, expect, mock, test } from "bun:test"
+import type {
+  ProjectAnalyticsDep,
+  ProjectCommandDeps,
+  ProjectDiffStoreDep,
+  ProjectStoreDep,
+  ProjectTerminalsDep,
+  ProjectUpdateManagerDep,
+} from "./ws-router-project"
+import { handleProjectCommand } from "./ws-router-project"
+import type { ClientCommand, ServerEnvelope } from "../shared/protocol"
+import type { UpdateInstallResult, UpdateSnapshot } from "../shared/types"
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeStore(overrides: Partial<ProjectStoreDep> = {}): ProjectStoreDep {
+  return {
+    state: { projectIdsByPath: new Map() },
+    openProject: mock(async () => ({ id: "proj-1" })),
+    removeProject: mock(async () => {}),
+    getProject: mock(() => ({ id: "proj-1", localPath: "/tmp/proj" })),
+    setProjectStar: mock(async () => {}),
+    setSidebarProjectOrder: mock(async () => {}),
+    ...overrides,
+  }
+}
+
+function makeUpdateManager(overrides: Partial<ProjectUpdateManagerDep> = {}): ProjectUpdateManagerDep {
+  const base: UpdateSnapshot = {
+    currentVersion: "1.0.0",
+    latestVersion: "1.1.0",
+    status: "idle",
+    updateAvailable: true,
+    lastCheckedAt: null,
+    error: null,
+    installAction: "restart",
+    reloadRequestedAt: null,
+  }
+  const installResult: UpdateInstallResult = {
+    ok: true,
+    action: "restart",
+    errorCode: null,
+    userTitle: null,
+    userMessage: null,
+  }
+  return {
+    checkForUpdates: mock(async () => base),
+    installUpdate: mock(async () => installResult),
+    forceReload: mock(async () => installResult),
+    ...overrides,
+  }
+}
+
+function makeAnalytics(): ProjectAnalyticsDep & { events: string[] } {
+  const events: string[] = []
+  return {
+    events,
+    track: (event: string) => { events.push(event) },
+  }
+}
+
+function makeDiffStore(): ProjectDiffStoreDep {
+  return {
+    readPatch: mock(async () => ({ patch: "diff content" })),
+  }
+}
+
+function makeTerminals(): ProjectTerminalsDep {
+  return { closeByCwd: mock(() => {}) }
+}
+
+interface TestDeps extends ProjectCommandDeps {
+  sent: ServerEnvelope[]
+  sidebarBroadcasts: number
+}
+
+function makeDeps(
+  options: {
+    storeOverrides?: Partial<ProjectStoreDep>
+    updateManager?: ProjectUpdateManagerDep | null
+    importResult?: Partial<{ imported: number; updated: number; skipped: number; failed: number; newProjects: number }>
+    openExternalFn?: () => Promise<void>
+  } = {},
+): TestDeps {
+  const sent: ServerEnvelope[] = []
+  let sidebarBroadcasts = 0
+  const analytics = makeAnalytics()
+
+  return {
+    store: makeStore(options.storeOverrides),
+    updateManager: options.updateManager !== undefined ? options.updateManager : makeUpdateManager(),
+    diffStore: makeDiffStore(),
+    analytics,
+    terminals: makeTerminals(),
+    refreshDiscovery: mock(async () => []),
+    ensureProjectDirectory: mock(async () => {}),
+    resolveLocalPath: (p) => p,
+    importClaudeSessionsFn: mock(async () => ({
+      imported: 1,
+      updated: 0,
+      skipped: 0,
+      failed: 0,
+      newProjects: options.importResult?.newProjects ?? 0,
+      ...options.importResult,
+    })),
+    openExternalFn: options.openExternalFn ?? mock(async () => {}),
+    send: (envelope) => { sent.push(envelope) },
+    broadcastSidebar: mock(async () => { sidebarBroadcasts++ }),
+    sent,
+    get sidebarBroadcasts() { return sidebarBroadcasts },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("handleProjectCommand", () => {
+  // -------------------------------------------------------------------------
+  // Unknown / out-of-scope
+  // -------------------------------------------------------------------------
+
+  test("returns false for a non-project command", async () => {
+    const deps = makeDeps()
+    const handled = await handleProjectCommand(
+      deps,
+      { type: "chat.create" } as unknown as ClientCommand,
+      "r0",
+    )
+    expect(handled).toBe(false)
+    expect(deps.sent).toHaveLength(0)
+  })
+
+  // -------------------------------------------------------------------------
+  // system.ping
+  // -------------------------------------------------------------------------
+
+  test("system.ping — sends ack, returns true, no broadcast", async () => {
+    const deps = makeDeps()
+    const handled = await handleProjectCommand(deps, { type: "system.ping" }, "r1")
+    expect(handled).toBe(true)
+    expect(deps.sent).toHaveLength(1)
+    expect(deps.sent[0]).toMatchObject({ type: "ack", id: "r1" })
+    expect(deps.sidebarBroadcasts).toBe(0)
+  })
+
+  // -------------------------------------------------------------------------
+  // update.check
+  // -------------------------------------------------------------------------
+
+  test("update.check — no updateManager — returns fallback snapshot", async () => {
+    const deps = makeDeps({ updateManager: null })
+    const handled = await handleProjectCommand(
+      deps,
+      { type: "update.check", force: false },
+      "r2",
+    )
+    expect(handled).toBe(true)
+    expect(deps.sent).toHaveLength(1)
+    const ack = deps.sent[0] as { type: string; result: { status: string; error: string } }
+    expect(ack.result.status).toBe("error")
+    expect(ack.result.error).toContain("unavailable")
+  })
+
+  test("update.check — with updateManager — calls checkForUpdates", async () => {
+    const um = makeUpdateManager()
+    const deps = makeDeps({ updateManager: um })
+    const handled = await handleProjectCommand(
+      deps,
+      { type: "update.check", force: true },
+      "r3",
+    )
+    expect(handled).toBe(true)
+    expect(um.checkForUpdates as ReturnType<typeof mock>).toHaveBeenCalledWith({ force: true })
+    const ack = deps.sent[0] as { type: string; result: { currentVersion: string } }
+    expect(ack.result.currentVersion).toBe("1.0.0")
+  })
+
+  test("update.install — no updateManager — throws", async () => {
+    const deps = makeDeps({ updateManager: null })
+    await expect(
+      handleProjectCommand(deps, { type: "update.install", version: "1.1.0" }, "r4"),
+    ).rejects.toThrow("unavailable")
+  })
+
+  test("update.reload — calls forceReload, acks", async () => {
+    const um = makeUpdateManager()
+    const deps = makeDeps({ updateManager: um })
+    const handled = await handleProjectCommand(deps, { type: "update.reload" }, "r5")
+    expect(handled).toBe(true)
+    expect(um.forceReload as ReturnType<typeof mock>).toHaveBeenCalled()
+    expect(deps.sent[0]).toMatchObject({ type: "ack", id: "r5" })
+  })
+
+  // -------------------------------------------------------------------------
+  // project.open
+  // -------------------------------------------------------------------------
+
+  test("project.open — new project — tracks analytics, acks with projectId", async () => {
+    const deps = makeDeps({
+      storeOverrides: {
+        state: { projectIdsByPath: new Map() }, // path not in map → new
+        openProject: mock(async () => ({ id: "new-proj" })),
+      },
+    })
+    const handled = await handleProjectCommand(
+      deps,
+      { type: "project.open", localPath: "/tmp/newproj" },
+      "r6",
+    )
+    expect(handled).toBe(true)
+    const ack = deps.sent[0] as { type: string; result: { projectId: string } }
+    expect(ack.result.projectId).toBe("new-proj")
+    expect((deps.analytics as ReturnType<typeof makeAnalytics>).events).toContain("project_opened")
+    expect(deps.ensureProjectDirectory as ReturnType<typeof mock>).toHaveBeenCalledWith("/tmp/newproj")
+    expect(deps.refreshDiscovery as ReturnType<typeof mock>).toHaveBeenCalled()
+  })
+
+  test("project.open — existing project — skips analytics", async () => {
+    const deps = makeDeps({
+      storeOverrides: {
+        state: { projectIdsByPath: new Map([["/tmp/existing", "old-id"]]) },
+        openProject: mock(async () => ({ id: "old-id" })),
+      },
+    })
+    await handleProjectCommand(
+      deps,
+      { type: "project.open", localPath: "/tmp/existing" },
+      "r7",
+    )
+    expect((deps.analytics as ReturnType<typeof makeAnalytics>).events).not.toContain("project_opened")
+  })
+
+  // -------------------------------------------------------------------------
+  // project.create
+  // -------------------------------------------------------------------------
+
+  test("project.create — new project — tracks both analytics events, acks", async () => {
+    const deps = makeDeps({
+      storeOverrides: {
+        state: { projectIdsByPath: new Map() },
+        openProject: mock(async () => ({ id: "created-proj" })),
+      },
+    })
+    const handled = await handleProjectCommand(
+      deps,
+      { type: "project.create", localPath: "/tmp/created", title: "My App" },
+      "r8",
+    )
+    expect(handled).toBe(true)
+    const evts = (deps.analytics as ReturnType<typeof makeAnalytics>).events
+    expect(evts).toContain("project_opened")
+    expect(evts).toContain("project_created")
+    const ack = deps.sent[0] as { type: string; result: { projectId: string } }
+    expect(ack.result.projectId).toBe("created-proj")
+  })
+
+  // -------------------------------------------------------------------------
+  // project.remove
+  // -------------------------------------------------------------------------
+
+  test("project.remove — removes project, closes terminal, tracks analytics", async () => {
+    const closeByCwd = mock(() => {})
+    const removeProject = mock(async () => {})
+    const deps = makeDeps({
+      storeOverrides: {
+        getProject: mock(() => ({ id: "p1", localPath: "/tmp/proj" })),
+        removeProject,
+      },
+    })
+    ;(deps.terminals as ProjectTerminalsDep).closeByCwd = closeByCwd
+
+    const handled = await handleProjectCommand(
+      deps,
+      { type: "project.remove", projectId: "p1" },
+      "r9",
+    )
+    expect(handled).toBe(true)
+    expect(removeProject as ReturnType<typeof mock>).toHaveBeenCalledWith("p1")
+    expect(closeByCwd as ReturnType<typeof mock>).toHaveBeenCalledWith("/tmp/proj")
+    expect((deps.analytics as ReturnType<typeof makeAnalytics>).events).toContain("project_removed")
+    expect(deps.sent[0]).toMatchObject({ type: "ack", id: "r9" })
+  })
+
+  // -------------------------------------------------------------------------
+  // project.setStar
+  // -------------------------------------------------------------------------
+
+  test("project.setStar — sets star, acks, broadcasts sidebar", async () => {
+    const setProjectStar = mock(async () => {})
+    const deps = makeDeps({ storeOverrides: { setProjectStar } })
+    const handled = await handleProjectCommand(
+      deps,
+      { type: "project.setStar", projectId: "p2", starred: true },
+      "r10",
+    )
+    expect(handled).toBe(true)
+    expect(setProjectStar as ReturnType<typeof mock>).toHaveBeenCalledWith("p2", true)
+    expect(deps.sidebarBroadcasts).toBe(1)
+    expect(deps.sent[0]).toMatchObject({ type: "ack", id: "r10" })
+  })
+
+  // -------------------------------------------------------------------------
+  // project.readDiffPatch
+  // -------------------------------------------------------------------------
+
+  test("project.readDiffPatch — returns patch content", async () => {
+    const deps = makeDeps({
+      storeOverrides: {
+        getProject: mock(() => ({ id: "p3", localPath: "/tmp/proj3" })),
+      },
+    })
+    const handled = await handleProjectCommand(
+      deps,
+      { type: "project.readDiffPatch", projectId: "p3", path: "src/foo.ts" },
+      "r11",
+    )
+    expect(handled).toBe(true)
+    const ack = deps.sent[0] as { type: string; result: { patch: string } }
+    expect(ack.result.patch).toBe("diff content")
+    expect(deps.diffStore.readPatch as ReturnType<typeof mock>).toHaveBeenCalledWith({
+      projectPath: "/tmp/proj3",
+      path: "src/foo.ts",
+    })
+  })
+
+  test("project.readDiffPatch — missing project — throws Project not found", async () => {
+    const deps = makeDeps({
+      storeOverrides: {
+        getProject: mock(() => undefined),
+      },
+    })
+    await expect(
+      handleProjectCommand(
+        deps,
+        { type: "project.readDiffPatch", projectId: "ghost", path: "foo.ts" },
+        "r12",
+      ),
+    ).rejects.toThrow("Project not found")
+  })
+
+  // -------------------------------------------------------------------------
+  // sessions.importClaude
+  // -------------------------------------------------------------------------
+
+  test("sessions.importClaude — imports sessions, acks, broadcasts sidebar", async () => {
+    const deps = makeDeps({ importResult: { imported: 3, newProjects: 0 } })
+    const handled = await handleProjectCommand(deps, { type: "sessions.importClaude" }, "r13")
+    expect(handled).toBe(true)
+    const ack = deps.sent[0] as { type: string; result: { imported: number } }
+    expect(ack.result.imported).toBe(3)
+    expect(deps.sidebarBroadcasts).toBe(1)
+  })
+
+  test("sessions.importClaude — newProjects > 0 — calls refreshDiscovery", async () => {
+    const deps = makeDeps({ importResult: { imported: 1, newProjects: 2 } })
+    await handleProjectCommand(deps, { type: "sessions.importClaude" }, "r14")
+    expect(deps.refreshDiscovery as ReturnType<typeof mock>).toHaveBeenCalled()
+  })
+
+  // -------------------------------------------------------------------------
+  // sidebar.reorderProjectGroups
+  // -------------------------------------------------------------------------
+
+  test("sidebar.reorderProjectGroups — sets order, acks, broadcasts sidebar", async () => {
+    const setSidebarProjectOrder = mock(async () => {})
+    const deps = makeDeps({ storeOverrides: { setSidebarProjectOrder } })
+    const handled = await handleProjectCommand(
+      deps,
+      { type: "sidebar.reorderProjectGroups", projectIds: ["p1", "p2"] },
+      "r15",
+    )
+    expect(handled).toBe(true)
+    expect(setSidebarProjectOrder as ReturnType<typeof mock>).toHaveBeenCalledWith(["p1", "p2"])
+    expect(deps.sidebarBroadcasts).toBe(1)
+    expect(deps.sent[0]).toMatchObject({ type: "ack", id: "r15" })
+  })
+
+  // -------------------------------------------------------------------------
+  // system.openExternal
+  // -------------------------------------------------------------------------
+
+  test("system.openExternal — calls openExternalFn, acks", async () => {
+    const openExternalFn = mock(async () => {})
+    const deps = makeDeps({ openExternalFn })
+    const cmd: ClientCommand = {
+      type: "system.openExternal",
+      kind: "external",
+      target: "https://example.com",
+    } as unknown as ClientCommand
+    const handled = await handleProjectCommand(deps, cmd, "r16")
+    expect(handled).toBe(true)
+    expect(openExternalFn as ReturnType<typeof mock>).toHaveBeenCalledWith(cmd)
+    expect(deps.sent[0]).toMatchObject({ type: "ack", id: "r16" })
+  })
+})