saeeol 1.2.4 → 1.2.7

package/bin/saeeol.cjs

@@ -180,7 +180,8 @@ if (resolved) {
 }
 
 // Fallback: run source with bun if available
-const indexPath = path.join(scriptDir, "src", "index.ts")
+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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
-  "version": "1.2.4",
+  "version": "1.2.7",
   "name": "saeeol",
   "type": "module",
   "license": "Apache-2.0",
@@ -50,8 +50,8 @@
     "@babel/core": "7.28.4",
     "@effect/language-service": "0.84.2",
     "@octokit/webhooks-types": "7.6.1",
-    "@saeeol/script": "7.3.2",
-    "@saeeol/core": "7.3.2",
+    "@saeeol/script": "7.3.4",
+    "@saeeol/core": "7.3.4",
     "@parcel/watcher-darwin-arm64": "2.5.1",
     "@parcel/watcher-darwin-x64": "2.5.1",
     "@parcel/watcher-linux-arm64-glibc": "2.5.1",
@@ -133,14 +133,14 @@
     "@parcel/watcher": "2.5.1",
     "@pierre/diffs": "1.1.0-beta.18",
     "@saeeol/boxes": "0.2.0",
-    "@saeeol/core": "7.3.2",
-    "@saeeol/gateway": "7.3.2",
-    "@saeeol/i18n": "7.3.2",
-    "@saeeol/indexing": "7.3.2",
-    "@saeeol/plugin": "7.3.3",
-    "@saeeol/script": "7.3.2",
-    "@saeeol/sdk": "7.3.3",
-    "@saeeol/telemetry": "7.3.2",
+    "@saeeol/core": "7.3.4",
+    "@saeeol/gateway": "7.3.3",
+    "@saeeol/i18n": "7.3.4",
+    "@saeeol/indexing": "7.3.3",
+    "@saeeol/plugin": "7.3.4",
+    "@saeeol/script": "7.3.4",
+    "@saeeol/sdk": "7.3.4",
+    "@saeeol/telemetry": "7.3.3",
     "@solid-primitives/event-bus": "1.1.2",
     "@solid-primitives/scheduled": "1.5.2",
     "@standard-schema/spec": "1.0.0",
@@ -202,5 +202,8 @@
   "overrides": {
     "drizzle-orm": "1.0.0-beta.19-d95b7a4"
   },
-  "peerDependencies": {}
+  "peerDependencies": {},
+  "files": [
+    "src"
+  ]
 }

package/src/ltm/config.ts

@@ -1,4 +1,4 @@
-/** LTM — 하드웨어 자동 감지 + 결정론적 LLM 파라미터 계산 */
+/** LTM — hardware auto-detection + deterministic LLM parameter calculation */
 
 import os from "os"
 import { Effect } from "effect"
@@ -10,7 +10,7 @@ import type { HardwareProfile, LLMBakeParams, LTMConfig } from "./types"
 
 const log = Log.create({ service: "ltm/config" })
 
-// ── 기본 LTM 설정 ──
+// ── Default LTM config ──
 
 export const DEFAULT_LTM_CONFIG: LTMConfig = {
   enabled: false,
@@ -23,9 +23,9 @@ export const DEFAULT_LTM_CONFIG: LTMConfig = {
   retrieval: { topK: 5, minScore: 0.7, maxTokens: 2000 },
 }
 
-// ── 하드웨어 프로파일링 ──
+// ── Hardware profiling ──
 
-/** 시스템 하드웨어 정보 수집 */
+/** Collect system hardware information */
 export async function profileHardware(): Promise<HardwareProfile> {
   const gpu = await Effect.runPromise(GPU.profile)
   const totalRAMMB = Math.round(os.totalmem() / (1024 * 1024))
@@ -41,7 +41,7 @@ export async function profileHardware(): Promise<HardwareProfile> {
   }
 }
 
-/** 하드웨어 해시 (변경 감지용) */
+/** Hardware hash for change detection */
 export function hardwareHash(hw: HardwareProfile): string {
   const raw = `${hw.gpuCount}|${hw.totalVRAMMB}|${hw.totalRAMMB}|${hw.cpuCores}|${hw.cudaAvailable}`
   let h = 0
@@ -51,29 +51,29 @@ export function hardwareHash(hw: HardwareProfile): string {
   return h.toString(36)
 }
 
-// ── 임베딩 모델 선택 ──
+// ── Embedding model selection ──
 
-/** VRAM 기반 임베딩 모델 자동 선택 */
+/** Auto-select embedding model based on available VRAM */
 export function selectEmbeddingModel(hw: HardwareProfile) {
   const vram = hw.availableVRAMMB
-  // 한국어 지원 모델 우선
+  // Prefer multilingual (Korean-capable) models
   if (vram >= 3000 || hw.totalRAMMB >= 16000) return RAG.EMBEDDING_MODELS[3] // bge-m3, 1024d, 2.2GB
   if (vram >= 1500 || hw.totalRAMMB >= 8000) return RAG.EMBEDDING_MODELS[4] // nomic-embed, 768d, 550MB
   if (vram >= 500) return RAG.EMBEDDING_MODELS[0] // bge-small-en, 384d, 130MB
   return RAG.EMBEDDING_MODELS[5] // all-minilm-l6, 384d, 80MB
 }
 
-// ── Bake (결정론적 파라미터 계산) ──
+// ── Bake (deterministic parameter calculation) ──
 
-/**
- * 하드웨어 기반 LLM 파라미터를 계산하고 파일에 저장.
- * 한 번 계산되면 하드웨어가 바뀌지 않는 한 동일한 값 유지.
- */
+ /**
+  * Compute hardware-based LLM parameters and persist to disk.
+  * Once computed, the same values are reused as long as hardware doesn't change.
+  */
 export async function bake(hw: HardwareProfile): Promise<LLMBakeParams> {
   const existing = await readBake()
   const hash = hardwareHash(hw)
 
-  // 해시가 같으면 기존 파라미터 재사용 (결정론적)
+  // If hash matches, reuse existing params (deterministic)
   if (existing && existing.hardwareHash === hash) {
     log.info("bake: hardware unchanged, reusing existing params", { hash })
     return existing
@@ -96,7 +96,7 @@ export async function bake(hw: HardwareProfile): Promise<LLMBakeParams> {
   return params
 }
 
-// ── 영속화 ──
+// ── Persistence ──
 
 import path from "path"
 import { mkdir, readFile, writeFile } from "fs/promises"

package/src/ltm/events.ts

@@ -1,4 +1,4 @@
-/** LTM — BusEvent 정의 */
+/** LTM — BusEvent definitions */
 
 import { Schema } from "effect"
 import * as BusEvent from "@/bus/bus-event"

package/src/ltm/index.ts

@@ -1,4 +1,4 @@
-/** LTM — 장기 기억 공개 API */
+/** LTM — long-term memory public API */
 
 export * from "./types"
 export * as Config from "./config"

package/src/ltm/pipeline.ts

@@ -1,4 +1,4 @@
-/** LTM — 백그라운드 수집 파이프라인 */
+/** LTM — background collection pipeline */
 
 import { Effect } from "effect"
 import * as Log from "@saeeol/core/util/log"
@@ -11,7 +11,7 @@ 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 { SessionEvent } from "@/session/core/session-types"
+import { Event as SessionEvent } from "@/session/core/session-types"
 
 const log = Log.create({ service: "ltm/pipeline" })
 
@@ -19,9 +19,9 @@ let running = false
 let config: LTMConfig | undefined
 let unsubscribers: Array<() => void> = []
 
-// ── 파이프라인 수명 ──
+// ── Pipeline lifecycle ──
 
-/** 파이프라인 시작 */
+/** Start the pipeline */
 export async function start(cfg: LTMConfig, bake: LLMBakeParams): Promise<void> {
   if (running) return
   if (!cfg.enabled) return
@@ -31,7 +31,7 @@ export async function start(cfg: LTMConfig, bake: LLMBakeParams): Promise<void>
 
   log.info("pipeline starting", { model: bake.embeddingModel })
 
-  // 임베딩 서버 시작
+  // Start embedding server
   const server = await Embedder.start(bake)
   if (server.status !== "running") {
     log.error("embedding server failed to start, pipeline disabled")
@@ -39,7 +39,7 @@ export async function start(cfg: LTMConfig, bake: LLMBakeParams): Promise<void>
     return
   }
 
-  // 오래된 기억 정리
+  // Prune old memories
   if (cfg.episodic.enabled) {
     const pruned = await Store.prune(cfg.episodic.retainDays * 24 * 60 * 60 * 1000)
     if (pruned > 0) {
@@ -48,7 +48,7 @@ export async function start(cfg: LTMConfig, bake: LLMBakeParams): Promise<void>
     }
   }
 
-  // 기억 수 제한
+  // Enforce memory limit
   const count = await Store.count()
   if (count > cfg.maxMemories) {
     const excess = count - cfg.maxMemories
@@ -59,18 +59,18 @@ export async function start(cfg: LTMConfig, bake: LLMBakeParams): Promise<void>
     log.info("trimmed memories to max", { removed: toRemove.length })
   }
 
-  // BusEvent 구독 바인딩
+  // Bind BusEvent subscriptions
   bindSubscriptions()
 
   log.info("pipeline started", { memoryCount: await Store.count() })
 }
 
-/** 파이프라인 중지 */
+/** Stop the pipeline */
 export async function stop(): Promise<void> {
   if (!running) return
   running = false
 
-  // 구독 해제
+  // Unsubscribe
   for (const unsub of unsubscribers) {
     try { unsub() } catch { /* ignore */ }
   }
@@ -81,27 +81,27 @@ export async function stop(): Promise<void> {
   log.info("pipeline stopped")
 }
 
-/** 현재 상태 */
+/** Current state */
 export function isActive(): boolean {
   return running
 }
 
-// ── BusEvent 구독 바인딩 ──
+// ── BusEvent subscription binding ──
 
 function bindSubscriptions() {
   if (!config) return
 
-  // 1. 세션 diff → 에피소드 기억 (코드 변경 후 AI 응답 완료 시)
+  // 1. Session diff → episodic memory (after code change + AI response)
   const unsubDiff = Bus.subscribe(SessionEvent.Diff, async (event) => {
     if (!running || !config?.episodic.enabled) return
 
     const sessionID = event.properties.sessionID
-    // diff 이벤트는 assistant 응답 후 세션 상태가 업데이트될 때 발생
-    // 사용자 메시지와 assistant 응답을 모두 포함할 수 있는 컨텍스트로 처리
+    // diff events fire when session state is updated after an assistant response
+    // Contains both user message and assistant response context
     const diffs = event.properties.diff
     if (!diffs || diffs.length === 0) return
 
-    const summary = `code changes: ${diffs.map((d) => `${d.filePath} (${d.status})`).join(", ")}`
+    const summary = `code changes: ${diffs.map((d) => `${d.file} (${d.status})`).join(", ")}`
     try {
       const vector = await Embedder.embedOne(summary)
       const memory = {
@@ -129,7 +129,7 @@ function bindSubscriptions() {
   })
   unsubscribers.push(unsubDiff)
 
-  // 2. 세션 에러 → 에피소드 기억 (문제/해결 추적)
+  // 2. Session error → episodic memory (problem/resolution tracking)
   const unsubError = Bus.subscribe(SessionEvent.Error, async (event) => {
     if (!running || !config?.episodic.enabled) return
     const sessionID = event.properties.sessionID
@@ -169,9 +169,9 @@ function bindSubscriptions() {
   log.info("bus subscriptions bound", { count: unsubscribers.length })
 }
 
-// ── 직접 호출 핸들러 (외부에서 명시적으로 호출) ──
+// ── Direct-call handlers (called explicitly from external modules) ──
 
-/** 대화 메시지 → 에피소드 기억 */
+/** Conversation message → episodic memory */
 export async function onMessageCompleted(
   sessionID: string,
   projectID: string | undefined,
@@ -191,7 +191,7 @@ export async function onMessageCompleted(
   })
 }
 
-/** 파일 변경 → 시맨틱 기억 */
+/** File change → semantic memory */
 export async function onFileChanged(
   projectID: string,
   filePath: string,
@@ -199,14 +199,14 @@ export async function onFileChanged(
 ): Promise<void> {
   if (!running || !config?.semantic.enabled || !config.semantic.indexOnFileChange) return
 
-  // VRAM 스케줄러 확인 — 임베딩 작업 가능한지
+  // Check VRAM scheduler — can we run embedding?
   const canRun = await Scheduler.canRunEmbedding()
   if (!canRun) {
     log.info("skipping file indexing — VRAM budget exceeded", { filePath })
     return
   }
 
-  // 파일을 청크로 분할 (간단한 줄 기반)
+  // Split file into chunks (simple line-based)
   const lines = content.split("\n")
   const chunkSize = 50
   const chunks: Array<{ text: string; start: number; end: number }> = []
@@ -239,7 +239,7 @@ export async function onFileChanged(
   log.info("indexed file", { filePath, chunks: chunks.length })
 }
 
-/** 코드 편집 → 절차적 기억 */
+/** Code edit → procedural memory */
 export async function onCodeEdit(
   projectID: string | undefined,
   filePath: string,

package/src/ltm/scheduler.ts

@@ -1,4 +1,4 @@
-/** LTM — VRAM/작업 스케줄러 */
+/** LTM — VRAM/task scheduler */
 
 import * as Log from "@saeeol/core/util/log"
 import type { HardwareProfile } from "./types"
@@ -8,14 +8,19 @@ import { Effect } from "effect"
 
 const log = Log.create({ service: "ltm/scheduler" })
 
-/** 현재 할당 상태 */
+/** Current allocation state */
 export interface Allocation {
   llm: number
   embedding: number
   available: number
 }
 
-/** 현재 VRAM 할당 상태 조회 */
+/** Scheduling strategy */
+export type Strategy = "concurrent" | "alternating" | "cpu-fallback" | "no-gpu"
+
+// ── VRAM gauge ──
+
+/** Query current VRAM allocation state */
 export async function allocation(): Promise<Allocation> {
   const gpu = await Effect.runPromise(GPU.profile)
   const embVRAM = Embedder.vramUsage()
@@ -26,30 +31,99 @@ export async function allocation(): Promise<Allocation> {
   }
 }
 
-/** 임베딩 백그라운드 작업 실행 가능한지 판단 */
+/** Return the scheduling strategy */
+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"
+}
+
+// ── Execution decisions ──
+
+/** Whether embedding background work can run */
 export async function canRunEmbedding(): Promise<boolean> {
+  const strat = await strategy()
+  // no-gpu or cpu-fallback: always allowed (CPU processing)
+  if (strat === "no-gpu" || strat === "cpu-fallback") return true
+  // concurrent: always allowed
+  if (strat === "concurrent") return true
+  // alternating: need at least 2GB VRAM
   const alloc = await allocation()
-  // 최소 2GB VRAM 필요
   return alloc.available >= 2048
 }
 
-/** LLM과 임베딩 동시 실행 가능한지 판단 */
+/** Whether LLM and embedding can run concurrently */
 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 ↔ embedding time-sharing ──
 
-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"
+/** Called when LLM requests VRAM — pauses embedding if needed */
+export async function requestLLM(vramNeededMB: number): Promise<boolean> {
+  const strat = await strategy()
+
+  // concurrent strategy: both can run
+  if (strat === "concurrent") return true
+  // no-gpu: GPU not needed
+  if (strat === "no-gpu") return true
+
+  const alloc = await allocation()
+
+  // Sufficient VRAM — proceed as-is
+  if (alloc.available >= vramNeededMB) {
+    log.info("LLM request: enough VRAM", { available: alloc.available, needed: vramNeededMB })
+    return true
+  }
+
+  // alternating strategy: pause embedding to free 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: embedding already runs on CPU, GPU is LLM-exclusive
+  if (strat === "cpu-fallback") return true
+
+  log.warn("LLM request: insufficient VRAM", { available: alloc.available, needed: vramNeededMB })
+  return false
+}
+
+/** Resume embedding server — called when LLM goes idle */
+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/store.ts

@@ -1,4 +1,4 @@
-/** LTM — 파일시스템 기반 벡터 스토어 */
+/** LTM — filesystem-based vector store */
 
 import path from "path"
 import { mkdir, readFile, writeFile, readdir, rm, stat } from "fs/promises"
@@ -8,7 +8,7 @@ import type { Memory, MemoryType } from "./types"
 
 const log = Log.create({ service: "ltm/store" })
 
-// ── 코사인 유사도 ──
+// ── Cosine similarity ──
 
 function cosine(a: number[], b: number[]): number {
   let dot = 0
@@ -24,14 +24,16 @@ function cosine(a: number[], b: number[]): number {
   return denom === 0 ? 0 : dot / denom
 }
 
-// ── 파일 경로 ──
+// ── File paths ──
 
 function storeDir(): string {
   return path.join(Global.Path.data, "ltm", "memories")
 }
 
 function memoryPath(id: string): string {
-  return path.join(storeDir(), `${id}.json`)
+  // Sanitize special characters for safe filenames
+  const safe = id.replace(/[:<>\"|?*]/g, "_")
+  return path.join(storeDir(), `${safe}.json`)
 }
 
 function indexPath(): string {
@@ -42,7 +44,7 @@ async function ensure(): Promise<void> {
   await mkdir(storeDir(), { recursive: true })
 }
 
-// ── 인덱스 ──
+// ── Index ──
 
 interface Index {
   memories: Array<{ id: string; type: MemoryType; timestamp: number; source: string }>
@@ -62,7 +64,7 @@ async function writeIndex(idx: Index): Promise<void> {
   await writeFile(indexPath(), JSON.stringify(idx, null, 2))
 }
 
-// ── 공개 API ──
+// ── Public API ──
 
 export async function upsert(memory: Memory): Promise<void> {
   await ensure()
@@ -99,7 +101,7 @@ export async function search(
         candidates.push({ ...mem, score })
       }
     } catch {
-      // 파일 삭제됨 — 인덱스에서도 제거
+      // File deleted — remove from index too
     }
   }
 

package/src/ltm/types.ts

@@ -1,14 +1,14 @@
-/** LTM — 장기 기억 타입 정의 */
+/** LTM — long-term memory type definitions */
 
 import { Schema } from "effect"
 import { optionalOmitUndefined } from "@/util/schema"
 
-// ── 기억 유형 ──
+// ── Memory types ──
 
 export const MemoryType = Schema.Literals(["episodic", "semantic", "procedural"])
 export type MemoryType = Schema.Schema.Type<typeof MemoryType>
 
-// ── 기억 엔트리 ──
+// ── Memory entry ──
 
 export const MemoryMetadata = Schema.Struct({
   source: Schema.String,
@@ -30,7 +30,7 @@ export const Memory = Schema.Struct({
 })
 export type Memory = Schema.Schema.Type<typeof Memory>
 
-// ── 임베딩 서버 ──
+// ── Embedding server ──
 
 export const EmbedderStatus = Schema.Literals(["stopped", "starting", "running", "error"])
 export type EmbedderStatus = Schema.Schema.Type<typeof EmbedderStatus>
@@ -45,7 +45,7 @@ export const EmbeddingServer = Schema.Struct({
 })
 export type EmbeddingServer = Schema.Schema.Type<typeof EmbeddingServer>
 
-// ── 하드웨어 프로파일 ──
+// ── Hardware profile ──
 
 export const HardwareProfile = Schema.Struct({
   gpuCount: Schema.Number,
@@ -57,29 +57,29 @@ export const HardwareProfile = Schema.Struct({
 })
 export type HardwareProfile = Schema.Schema.Type<typeof HardwareProfile>
 
-// ── LLM 파라미터 (결정론적) ──
+// ── LLM parameters (deterministic) ──
 
 export const LLMBakeParams = Schema.Struct({
-  /** 임베딩 모델 ID */
+  /** Embedding model ID */
   embeddingModel: Schema.String,
-  /** 임베딩 차원 */
+  /** Embedding dimensions */
   embeddingDimensions: Schema.Number,
-  /** 임베딩 모델 VRAM 사용량 (MB) */
+  /** Embedding model VRAM usage (MB) */
   embeddingVRAMMB: Schema.Number,
-  /** 컨텍스트 길이 */
+  /** Context length */
   contextLength: Schema.Number,
-  /** 배치 사이즈 */
+  /** Batch size */
   batchSize: Schema.Number,
-  /** Ollama 스레드 수 */
+  /** Ollama thread count */
   numThread: Schema.Number,
-  /** GPU 레이어 수 (-1=전체) */
+  /** GPU layer count (-1=all) */
   numGPU: Schema.Number,
-  /** 생성 시 프로파일 감지 해시 (변경 시 재계산 트리거) */
+  /** Profile detection hash at generation time (triggers recompute on change) */
   hardwareHash: Schema.String,
 })
 export type LLMBakeParams = Schema.Schema.Type<typeof LLMBakeParams>
 
-// ── LTM 설정 ──
+// ── LTM configuration ──
 
 export const LTMConfig = Schema.Struct({
   enabled: Schema.Boolean,