saeeol 1.2.3 → 1.2.5

package/bin/saeeol.cjs

@@ -175,13 +175,30 @@ function findBinary(startDir) {
 }
 
 const resolved = findBinary(scriptDir)
-if (!resolved) {
-  console.error(
-    "It seems that your package manager failed to install the right version of the SAEEOL CLI for your platform. You can try manually installing " +
-      names.map((n) => `\"${n}\"`).join(" or ") +
-      " package",
-  )
-  process.exit(1)
+if (resolved) {
+  run(resolved)
 }
 
-run(resolved)
+// Fallback: run source with bun if available
+const srcDir = path.join(scriptDir, "..", "src")
+const indexPath = path.join(srcDir, "index.ts")
+if (fs.existsSync(indexPath)) {
+  const bunExe = process.platform === "win32" ? "bun.exe" : "bun"
+  try {
+    const which = childProcess.spawnSync(bunExe, ["--version"], { encoding: "utf8", timeout: 3000 })
+    if (which.status === 0) {
+      const result = childProcess.spawnSync(bunExe, [
+        "run", "--conditions=browser", indexPath, ...process.argv.slice(2)
+      ], { stdio: "inherit" })
+      const code = typeof result.status === "number" ? result.status : 0
+      process.exit(code)
+    }
+  } catch {}
+}
+
+console.error(
+  "It seems that your package manager failed to install the right version of the SAEEOL CLI for your platform. You can try manually installing " +
+    names.map((n) => `\"${n}\"`).join(" or ") +
+    " package, or install bun (https://bun.sh) to run from source",
+)
+process.exit(1)

package/package.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "name": "saeeol",
   "type": "module",
   "license": "Apache-2.0",

package/src/ltm/pipeline.ts

@@ -11,11 +11,13 @@ import * as Procedural from "@/ltm/memory/procedural"
 import * as Scheduler from "@/ltm/scheduler"
 import type { LTMConfig, LLMBakeParams } from "@/ltm/types"
 import { LTMEvent } from "@/ltm/events"
+import { Event as SessionEvent } from "@/session/core/session-types"
 
 const log = Log.create({ service: "ltm/pipeline" })
 
 let running = false
 let config: LTMConfig | undefined
+let unsubscribers: Array<() => void> = []
 
 // ── 파이프라인 수명 ──
 
@@ -57,6 +59,9 @@ export async function start(cfg: LTMConfig, bake: LLMBakeParams): Promise<void>
     log.info("trimmed memories to max", { removed: toRemove.length })
   }
 
+  // BusEvent 구독 바인딩
+  bindSubscriptions()
+
   log.info("pipeline started", { memoryCount: await Store.count() })
 }
 
@@ -64,6 +69,13 @@ export async function start(cfg: LTMConfig, bake: LLMBakeParams): Promise<void>
 export async function stop(): Promise<void> {
   if (!running) return
   running = false
+
+  // 구독 해제
+  for (const unsub of unsubscribers) {
+    try { unsub() } catch { /* ignore */ }
+  }
+  unsubscribers = []
+
   await Embedder.stop()
   config = undefined
   log.info("pipeline stopped")
@@ -74,7 +86,90 @@ export function isActive(): boolean {
   return running
 }
 
-// ── 이벤트 핸들러 ──
+// ── BusEvent 구독 바인딩 ──
+
+function bindSubscriptions() {
+  if (!config) return
+
+  // 1. 세션 diff → 에피소드 기억 (코드 변경 후 AI 응답 완료 시)
+  const unsubDiff = Bus.subscribe(SessionEvent.Diff, async (event) => {
+    if (!running || !config?.episodic.enabled) return
+
+    const sessionID = event.properties.sessionID
+    // diff 이벤트는 assistant 응답 후 세션 상태가 업데이트될 때 발생
+    // 사용자 메시지와 assistant 응답을 모두 포함할 수 있는 컨텍스트로 처리
+    const diffs = event.properties.diff
+    if (!diffs || diffs.length === 0) return
+
+    const summary = `code changes: ${diffs.map((d) => `${d.filePath} (${d.status})`).join(", ")}`
+    try {
+      const vector = await Embedder.embedOne(summary)
+      const memory = {
+        id: `epi:${sessionID}:${Date.now()}`,
+        type: "episodic" as const,
+        content: summary.slice(0, 500),
+        summary,
+        vector,
+        metadata: {
+          source: `session:${sessionID}`,
+          timestamp: Date.now(),
+          sessionID,
+          tags: ["code-change"],
+        },
+      }
+      await Store.upsert(memory)
+      void Bus.publish(LTMEvent.MemoryStored, {
+        id: memory.id,
+        type: memory.type,
+        source: memory.metadata.source,
+      })
+    } catch (e) {
+      log.error("failed to store session diff memory", { error: e })
+    }
+  })
+  unsubscribers.push(unsubDiff)
+
+  // 2. 세션 에러 → 에피소드 기억 (문제/해결 추적)
+  const unsubError = Bus.subscribe(SessionEvent.Error, async (event) => {
+    if (!running || !config?.episodic.enabled) return
+    const sessionID = event.properties.sessionID
+    if (!sessionID) return
+
+    const err = event.properties.error
+    if (!err) return
+
+    const summary = `error in session: ${typeof err === "object" ? JSON.stringify(err).slice(0, 200) : String(err).slice(0, 200)}`
+    try {
+      const vector = await Embedder.embedOne(summary)
+      const memory = {
+        id: `epi:err:${sessionID}:${Date.now()}`,
+        type: "episodic" as const,
+        content: summary.slice(0, 500),
+        summary,
+        vector,
+        metadata: {
+          source: `session:${sessionID}`,
+          timestamp: Date.now(),
+          sessionID,
+          tags: ["error"],
+        },
+      }
+      await Store.upsert(memory)
+      void Bus.publish(LTMEvent.MemoryStored, {
+        id: memory.id,
+        type: memory.type,
+        source: memory.metadata.source,
+      })
+    } catch (e) {
+      log.error("failed to store error memory", { error: e })
+    }
+  })
+  unsubscribers.push(unsubError)
+
+  log.info("bus subscriptions bound", { count: unsubscribers.length })
+}
+
+// ── 직접 호출 핸들러 (외부에서 명시적으로 호출) ──
 
 /** 대화 메시지 → 에피소드 기억 */
 export async function onMessageCompleted(
@@ -104,6 +199,13 @@ export async function onFileChanged(
 ): Promise<void> {
   if (!running || !config?.semantic.enabled || !config.semantic.indexOnFileChange) return
 
+  // VRAM 스케줄러 확인 — 임베딩 작업 가능한지
+  const canRun = await Scheduler.canRunEmbedding()
+  if (!canRun) {
+    log.info("skipping file indexing — VRAM budget exceeded", { filePath })
+    return
+  }
+
   // 파일을 청크로 분할 (간단한 줄 기반)
   const lines = content.split("\n")
   const chunkSize = 50

package/src/ltm/scheduler.ts

@@ -15,6 +15,11 @@ export interface Allocation {
   available: number
 }
 
+/** 스케줄링 전략 */
+export type Strategy = "concurrent" | "alternating" | "cpu-fallback" | "no-gpu"
+
+// ── VRAM 게이지 ──
+
 /** 현재 VRAM 할당 상태 조회 */
 export async function allocation(): Promise<Allocation> {
   const gpu = await Effect.runPromise(GPU.profile)
@@ -26,30 +31,99 @@ export async function allocation(): Promise<Allocation> {
   }
 }
 
+/** 스케줄링 전략 반환 */
+export async function strategy(): Promise<Strategy> {
+  const gpu = await Effect.runPromise(GPU.profile)
+  if (!gpu.cudaAvailable) return "no-gpu"
+  if (gpu.totalVRAMMB >= 16384) return "concurrent"
+  if (gpu.totalVRAMMB >= 8192) return "alternating"
+  return "cpu-fallback"
+}
+
+// ── 실행 판정 ──
+
 /** 임베딩 백그라운드 작업 실행 가능한지 판단 */
 export async function canRunEmbedding(): Promise<boolean> {
+  const strat = await strategy()
+  // no-gpu나 cpu-fallback에서는 항상 가능 (CPU 처리)
+  if (strat === "no-gpu" || strat === "cpu-fallback") return true
+  // concurrent에서는 항상 가능
+  if (strat === "concurrent") return true
+  // alternating: VRAM 최소 2GB 필요
   const alloc = await allocation()
-  // 최소 2GB VRAM 필요
   return alloc.available >= 2048
 }
 
 /** LLM과 임베딩 동시 실행 가능한지 판단 */
 export async function canRunConcurrent(hw: HardwareProfile): Promise<boolean> {
-  // 16GB 이상 VRAM이면 항상 동시 실행 가능
   if (hw.totalVRAMMB >= 16384) return true
-  // 8GB 이상이면 임베딩 모델이 1GB 이하일 때 가능
   if (hw.totalVRAMMB >= 8192 && Embedder.vramUsage() <= 1024) return true
-  // 그 외는 교대 실행
   return false
 }
 
-/** 스케줄링 전략 반환 */
-export type Strategy = "concurrent" | "alternating" | "cpu-fallback" | "no-gpu"
+// ── LLM ↔ 임베딩 교대 실행 ──
 
-export async function strategy(): Promise<Strategy> {
-  const gpu = await Effect.runPromise(GPU.profile)
-  if (!gpu.cudaAvailable) return "no-gpu"
-  if (gpu.totalVRAMMB >= 16384) return "concurrent"
-  if (gpu.totalVRAMMB >= 8192) return "alternating"
-  return "cpu-fallback"
+/** LLM이 VRAM을 요청할 때 호출 — 필요시 임베딩 일시정지 */
+export async function requestLLM(vramNeededMB: number): Promise<boolean> {
+  const strat = await strategy()
+
+  // concurrent 전략: 둘 다 실행 가능
+  if (strat === "concurrent") return true
+  // no-gpu: GPU 필요 없음
+  if (strat === "no-gpu") return true
+
+  const alloc = await allocation()
+
+  // 충분한 VRAM이 있으면 그대로 진행
+  if (alloc.available >= vramNeededMB) {
+    log.info("LLM request: enough VRAM", { available: alloc.available, needed: vramNeededMB })
+    return true
+  }
+
+  // alternating 전략: 임베딩 서버를 일시정지하여 VRAM 확보
+  if (strat === "alternating" && alloc.embedding > 0) {
+    log.info("LLM request: pausing embedding to free VRAM", {
+      embedding: alloc.embedding,
+      needed: vramNeededMB,
+    })
+    await Embedder.stop()
+    return true
+  }
+
+  // cpu-fallback: 임베딩은 이미 CPU에서 실행 중, GPU는 LLM 전용
+  if (strat === "cpu-fallback") return true
+
+  log.warn("LLM request: insufficient VRAM", { available: alloc.available, needed: vramNeededMB })
+  return false
+}
+
+/** 임베딩 재시작 — LLM 유휴 시 호출 */
+export async function resumeEmbedding(bake: {
+  embeddingModel: string
+  embeddingDimensions: number
+}): Promise<void> {
+  const current = Embedder.status()
+  if (current?.status === "running") return
+
+  const canRun = await canRunEmbedding()
+  if (!canRun) {
+    log.info("embedder resume skipped — VRAM budget exceeded")
+    return
+  }
+
+  log.info("resuming embedding server after LLM idle")
+  try {
+    await Embedder.start({
+      embeddingModel: bake.embeddingModel,
+      embeddingDimensions: bake.embeddingDimensions,
+      embeddingVRAMMB: 0,
+      contextLength: 4096,
+      batchSize: 16,
+      numThread: 4,
+      numGPU: 0,
+      hardwareHash: "",
+    })
+  } catch (e) {
+    log.error("failed to resume embedding server", { error: e })
+  }
 }

package/src/ltm/types.ts

@@ -38,7 +38,7 @@ export type EmbedderStatus = Schema.Schema.Type<typeof EmbedderStatus>
 export const EmbeddingServer = Schema.Struct({
   id: Schema.String,
   model: Schema.String,
-  status: EmbedderStatus,
+  status: Schema.mutable(EmbedderStatus),
   endpoint: Schema.String,
   dimensions: Schema.Number,
   vramMB: Schema.Number,

package/src/provider/local/embedder.ts

@@ -151,7 +151,7 @@ export async function start(bake: LLMBakeParams): Promise<EmbeddingServer> {
   const running = await isOllamaRunning(endpoint)
   if (!running) {
     log.warn("Ollama not running, embedding server unavailable", { endpoint })
-    server.status = "error"
+    server = { ...server, status: "error" }
     void Bus.publish(LTMEvent.EmbedderStatusChanged, { status: "error", model: bake.embeddingModel })
     return server
   }
@@ -173,13 +173,13 @@ export async function start(bake: LLMBakeParams): Promise<EmbeddingServer> {
       log.info("model warmed up", { model: ollamaModel })
     } catch (e) {
       log.error("warmup failed", { model: ollamaModel, error: e })
-      server.status = "error"
+      server = { ...server, status: "error" }
       void Bus.publish(LTMEvent.EmbedderStatusChanged, { status: "error", model: bake.embeddingModel })
       return server
     }
   }
 
-  server.status = "running"
+    server = { ...server, status: "running" }
   void Bus.publish(LTMEvent.EmbedderStatusChanged, { status: "running", model: bake.embeddingModel })
   log.info("embedding server started", { model: bake.embeddingModel, dimensions: bake.embeddingDimensions })
 

package/test/ltm/ltm.test.ts

@@ -0,0 +1,230 @@
+/** LTM unit tests — store, retrieval, embedder cycle */
+
+import { describe, test, expect, beforeEach, afterEach } from "bun:test"
+import path from "path"
+import { mkdir, rm } from "fs/promises"
+import * as Store from "@/ltm/store"
+import * as Retrieval from "@/ltm/retrieval"
+import type { Memory, LTMConfig } from "@/ltm/types"
+import * as Episodic from "@/ltm/memory/episodic"
+import * as Procedural from "@/ltm/memory/procedural"
+
+// ── Mock embedder — Ollama 없이 테스트 ──
+
+const mockVectors = new Map<string, number[]>()
+
+/** 간단한 mock 임베딩 (텍스트 해시 기반) */
+function mockEmbed(text: string): number[] {
+  if (mockVectors.has(text)) return mockVectors.get(text)!
+  const vector = Array.from({ length: 384 }, (_, i) => {
+    const code = text.charCodeAt(i % text.length) || 0
+    return Math.sin(code * (i + 1)) * 0.5 + 0.5
+  })
+  mockVectors.set(text, vector)
+  return vector
+}
+
+// 테스트 설정
+const testConfig: LTMConfig = {
+  enabled: true,
+  embeddingModel: "mock",
+  vectorStore: "filesystem",
+  maxMemories: 100,
+  episodic: { enabled: true, summaryInterval: 5, retainDays: 90 },
+  semantic: { enabled: true, indexOnFileChange: true },
+  procedural: { enabled: true, trackPreferences: true },
+  retrieval: { topK: 5, minScore: 0.5, maxTokens: 2000 },
+}
+
+// ── Store 테스트 ──
+
+describe("LTM Store", () => {
+  test("upsert and search", async () => {
+    const vector = mockEmbed("hello world test")
+    const memory: Memory = {
+      id: "test:1",
+      type: "episodic",
+      content: "test content about hello world",
+      summary: "hello world test",
+      vector,
+      metadata: {
+        source: "test:unit",
+        timestamp: Date.now(),
+        tags: ["test"],
+      },
+    }
+
+    await Store.upsert(memory)
+    const results = await Store.search(vector, { topK: 5, minScore: 0.0 })
+    expect(results.length).toBeGreaterThan(0)
+    expect(results[0]!.id).toBe("test:1")
+  })
+
+  test("search filters by type", async () => {
+    const v1 = mockEmbed("episodic query")
+    await Store.upsert({
+      id: "test:epi",
+      type: "episodic",
+      content: "episodic content",
+      summary: "episodic query",
+      vector: v1,
+      metadata: { source: "test", timestamp: Date.now(), tags: [] },
+    })
+
+    const v2 = mockEmbed("semantic code query")
+    await Store.upsert({
+      id: "test:sem",
+      type: "semantic",
+      content: "code content",
+      summary: "semantic code query",
+      vector: v2,
+      metadata: { source: "test", timestamp: Date.now(), tags: [] },
+    })
+
+    const results = await Store.search(v1, { topK: 5, minScore: 0.0, type: "episodic" })
+    expect(results.every((m) => m.type === "episodic")).toBe(true)
+  })
+
+  test("remove deletes memories", async () => {
+    const id = `test:rm:${Date.now()}`
+    await Store.upsert({
+      id,
+      type: "episodic",
+      content: "to be removed",
+      summary: "remove test",
+      vector: mockEmbed("remove test"),
+      metadata: { source: "test", timestamp: Date.now(), tags: [] },
+    })
+
+    const before = await Store.count()
+    await Store.remove([id])
+    const after = await Store.count()
+    expect(after).toBeLessThanOrEqual(before)
+  })
+
+  test("prune removes old memories", async () => {
+    const oldTimestamp = Date.now() - 100 * 24 * 60 * 60 * 1000 // 100 days ago
+    const id = `test:old:${Date.now()}`
+    await Store.upsert({
+      id,
+      type: "episodic",
+      content: "old memory",
+      summary: "old memory content",
+      vector: mockEmbed("old memory content"),
+      metadata: { source: "test", timestamp: oldTimestamp, tags: [] },
+    })
+
+    const pruned = await Store.prune(90 * 24 * 60 * 60 * 1000) // 90 days
+    expect(pruned).toBeGreaterThanOrEqual(0)
+  })
+
+  test("upsert updates existing memory", async () => {
+    const id = "test:update"
+    const v1 = mockEmbed("version 1")
+    await Store.upsert({
+      id,
+      type: "semantic",
+      content: "version 1",
+      summary: "version 1",
+      vector: v1,
+      metadata: { source: "test", timestamp: 1, tags: [] },
+    })
+
+    const v2 = mockEmbed("version 2 updated")
+    await Store.upsert({
+      id,
+      type: "semantic",
+      content: "version 2",
+      summary: "version 2 updated",
+      vector: v2,
+      metadata: { source: "test", timestamp: 2, tags: [] },
+    })
+
+    const all = await Store.list()
+    const found = all.find((m) => m.id === id)
+    expect(found).toBeDefined()
+    expect(found!.content).toBe("version 2")
+  })
+
+  test("count returns total memories", async () => {
+    const count = await Store.count()
+    expect(typeof count).toBe("number")
+    expect(count).toBeGreaterThanOrEqual(0)
+  })
+})
+
+// ── Episodic Memory 테스트 ──
+
+describe("LTM Episodic Memory", () => {
+  test("shouldSummarize triggers at interval", () => {
+    expect(Episodic.shouldSummarize(10, 10)).toBe(true)
+    expect(Episodic.shouldSummarize(5, 10)).toBe(false)
+    expect(Episodic.shouldSummarize(20, 10)).toBe(true)
+    expect(Episodic.shouldSummarize(0, 10)).toBe(false)
+  })
+})
+
+// ── Procedural Memory 테스트 ──
+
+describe("LTM Procedural Memory", () => {
+  test("extractStyleSignals detects indentation", () => {
+    const signals = Procedural.extractStyleSignals("test.ts", "const x = 1\n  const y = 2\n  const z = 3")
+    const indent = signals.find((s) => s.pattern === "indent")
+    expect(indent).toBeDefined()
+    expect(indent!.evidence).toContain("2-space")
+  })
+
+  test("extractStyleSignals detects Korean comments", () => {
+    const signals = Procedural.extractStyleSignals("test.ts", "// 한국어 주석\nconst x = 1")
+    const commentLang = signals.find((s) => s.pattern === "comment-language")
+    expect(commentLang).toBeDefined()
+    expect(commentLang!.evidence).toContain("Korean")
+  })
+
+  test("extractStyleSignals detects quote style", () => {
+    const signals = Procedural.extractStyleSignals("test.ts", "const a = 'hello'\nconst b = 'world'\nconst c = 'test'")
+    const quotes = signals.find((s) => s.pattern === "quotes")
+    expect(quotes).toBeDefined()
+  })
+
+  test("extractStyleSignals returns empty for empty file", () => {
+    const signals = Procedural.extractStyleSignals("test.txt", "")
+    expect(signals).toBeArray()
+  })
+})
+
+// ── Retrieval 포맷 테스트 ──
+
+describe("LTM Retrieval", () => {
+  test("format produces context block", () => {
+    const memories: Memory[] = [
+      {
+        id: "test:r1",
+        type: "episodic",
+        content: "auth bug fix",
+        summary: "fixed CSRF vulnerability in auth/login.ts",
+        vector: [],
+        metadata: { source: "session:abc", timestamp: Date.now(), tags: ["fix", "auth"] },
+      },
+      {
+        id: "test:r2",
+        type: "semantic",
+        content: "express middleware",
+        summary: "project uses Express middleware chain pattern",
+        vector: [],
+        metadata: { source: "file:src/app.ts", timestamp: Date.now(), tags: ["architecture"] },
+      },
+    ]
+
+    const formatted = Retrieval.format(memories)
+    expect(formatted).toContain("[long-term memory")
+    expect(formatted).toContain("episodic")
+    expect(formatted).toContain("semantic")
+    expect(formatted).toContain("CSRF")
+  })
+
+  test("format returns empty for no memories", () => {
+    const formatted = Retrieval.format([])
+    expect(formatted).toBe("")
+  })
+})

package/test/server/contract.test.ts

@@ -0,0 +1,231 @@
+/**
+ * contract.test.ts — SAEEOL 서버 계약 테스트
+ *
+ * closebook 패턴 기반:
+ * - response-conformance: Zod 스키마로 응답 바디 적합성 검사
+ * - consumer-contract: SDK/클라이언트가 기대하는 API 응답 스키마 검증
+ * - stateful-api-testing: 세션 생성 → 목록 조회 순차 테스트
+ *
+ * Hono app.request()로 실제 HTTP 서버 없이 테스트.
+ * Bun test + Effect + zod 검증.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { Flag } from "@saeeol/core/flag/flag"
+import { Server } from "../../src/server/server"
+import { resetDatabase } from "../fixture/db"
+import { disposeAllInstances, tmpdir } from "../fixture/fixture"
+import * as Log from "@saeeol/core/util/log"
+import { z } from "zod"
+
+void Log.init({ print: false })
+
+const original = Flag.SAEEOL_EXPERIMENTAL_HTTPAPI
+
+function app(experimental = true) {
+	Flag.SAEEOL_EXPERIMENTAL_HTTPAPI = experimental
+	return experimental ? Server.Default().app : Server.Legacy().app
+}
+
+// ── Zod 스키마 (계약: 클라이언트가 기대하는 응답 형태) ──
+
+const HealthSchema = z.object({
+	healthy: z.boolean(),
+	version: z.string(),
+})
+
+const ConfigSchema = z.object({
+	model: z.string().optional(),
+	username: z.string().optional(),
+}).passthrough()
+
+const SessionListSchema = z.array(z.object({
+	id: z.string(),
+	title: z.string().optional(),
+	createdAt: z.number().optional(),
+}).passthrough())
+
+const SessionCreateSchema = z.object({
+	id: z.string(),
+}).passthrough()
+
+const AgentListSchema = z.array(z.unknown())
+
+// ── 응답 적합성 검증 (closebook: response-conformance) ──
+
+function checkConformance<T extends z.ZodType>(
+	body: unknown,
+	status: number,
+	schema: T,
+	allowedStatuses: number[] = [200],
+): { ok: boolean; violations: string[] } {
+	const violations: string[] = []
+
+	if (!allowedStatuses.includes(status)) {
+		violations.push(`status: expected ${allowedStatuses.join("/")}, got ${status}`)
+	}
+
+	const parsed = schema.safeParse(body)
+	if (!parsed.success) {
+		for (const issue of parsed.error.issues) {
+			violations.push(`${issue.path.join(".") || "(root)"}: ${issue.message}`)
+		}
+	}
+
+	return { ok: violations.length === 0, violations }
+}
+
+// ── 테스트 ──
+
+describe("SAEEOL server contract tests", () => {
+	afterEach(async () => {
+		Flag.SAEEOL_EXPERIMENTAL_HTTPAPI = original
+		await disposeAllInstances()
+	})
+
+	describe("GET /global/health", () => {
+		test("returns valid health response (legacy)", async () => {
+			const res = await app(false).request("/global/health")
+			const body = await res.json()
+			expect(res.status).toBe(200)
+			const { ok, violations } = checkConformance(body, res.status, HealthSchema)
+			expect(ok).toBe(true)
+			if (!ok) console.error("Health violations:", violations)
+		})
+
+		test("returns valid health response (experimental)", async () => {
+			const res = await app(true).request("/global/health")
+			const body = await res.json()
+			expect(res.status).toBe(200)
+			const { ok, violations } = checkConformance(body, res.status, HealthSchema)
+			expect(ok).toBe(true)
+			if (!ok) console.error("Health violations:", violations)
+		})
+	})
+
+	describe("GET /global/config", () => {
+		test("returns valid config response", async () => {
+			await using tmp = await tmpdir({ config: {} })
+			const res = await app(false).request("/global/config", {
+				headers: { "x-saeeol-directory": tmp.path },
+			})
+			const body = await res.json()
+			const { ok, violations } = checkConformance(body, res.status, ConfigSchema)
+			expect(ok).toBe(true)
+			if (!ok) console.error("Config violations:", violations)
+		})
+	})
+
+	describe("GET /agent", () => {
+		test("returns agent list", async () => {
+			await using tmp = await tmpdir({ config: {} })
+			const res = await app(false).request("/agent", {
+				headers: { "x-saeeol-directory": tmp.path },
+			})
+			const body = await res.json()
+			const { ok, violations } = checkConformance(body, res.status, AgentListSchema)
+			expect(ok).toBe(true)
+			if (!ok) console.error("Agent violations:", violations)
+		})
+	})
+
+	// ── 상태 순차 테스트 (closebook: stateful-api-testing) ──
+
+	describe("session lifecycle", () => {
+		test("create → list flow", async () => {
+			await using tmp = await tmpdir({ git: true, config: {} })
+			const headers = { "x-saeeol-directory": tmp.path, "Content-Type": "application/json" }
+
+			// Step 1: 세션 생성
+			const createRes = await app(false).request("/session", {
+				method: "POST",
+				headers,
+				body: JSON.stringify({ title: "contract-test" }),
+			})
+			const createBody = await createRes.json()
+			const { ok: createOk, violations: createViolations } = checkConformance(
+				createBody,
+				createRes.status,
+				SessionCreateSchema,
+			)
+			expect(createOk).toBe(true)
+			if (!createOk) console.error("Session create violations:", createViolations)
+
+			// Step 2: 세션 목록
+			const listRes = await app(false).request("/session", { headers })
+			const listBody = await listRes.json()
+			const { ok: listOk, violations: listViolations } = checkConformance(
+				listBody,
+				listRes.status,
+				SessionListSchema,
+			)
+			expect(listOk).toBe(true)
+			if (!listOk) console.error("Session list violations:", listViolations)
+			expect(listBody.length).toBeGreaterThanOrEqual(1)
+		})
+	})
+
+	describe("unknown route", () => {
+		test("returns 404 for unknown endpoints", async () => {
+			const res = await app(false).request("/nonexistent")
+			expect(res.status).toBe(404)
+		})
+	})
+
+	// ── 계약 파일 생성 (closebook: consumer-contract) ──
+
+	describe("pact artifact generation", () => {
+		test("collects verified interactions into contract", async () => {
+			await using tmp = await tmpdir({ config: {} })
+			const headers = { "x-saeeol-directory": tmp.path }
+			const interactions = []
+
+			// Health 인터랙션
+			const healthRes = await app(false).request("/global/health")
+			const healthBody = await healthRes.json()
+			interactions.push({
+				description: "health check",
+				providerStates: [],
+				request: { method: "GET", path: "/global/health" },
+				response: { status: healthRes.status, body: healthBody },
+			})
+
+			// Config 인터랙션
+			const configRes = await app(false).request("/global/config", { headers })
+			const configBody = await configRes.json()
+			interactions.push({
+				description: "global config",
+				providerStates: [],
+				request: { method: "GET", path: "/global/config" },
+				response: { status: configRes.status, body: configBody },
+			})
+
+			// Agent 인터랙션
+			const agentRes = await app(false).request("/agent", { headers })
+			const agentBody = await agentRes.json()
+			interactions.push({
+				description: "agent list",
+				providerStates: [],
+				request: { method: "GET", path: "/agent" },
+				response: { status: agentRes.status, body: agentBody },
+			})
+
+			// 계약 파일 검증
+			const pact = {
+				consumer: { name: "saeeol-vscode" },
+				provider: { name: "saeeol-server" },
+				interactions,
+				metadata: { version: "1.0.0" },
+			}
+
+			expect(pact.interactions.length).toBe(3)
+			for (const ix of pact.interactions) {
+				expect(ix).toHaveProperty("description")
+				expect(ix).toHaveProperty("request")
+				expect(ix).toHaveProperty("response")
+				expect(ix.response.status).toBeLessThan(500)
+			}
+		})
+	})
+})