zesdex/docs/CODEMAPS/backend.md

Backend & Infrastructure

Semua implementasi I/O ada di apps/infrastructure/src/. Layer ini mengimplementasikan port/trait yang didefinisikan di apps/domain/.

LLM Client (infrastructure/src/llm/)

Wrapper di atas provider OpenAI-compatible:

• provider/ — LlmClient: HTTP client dengan reqwest::blocking (sync) untuk agent turn, dan async streaming untuk preview
• Request/Response — ChatMessage, ChatCompletionRequest, ChatCompletionResponse dengan support tool calls
• Streaming — SSE event parser untuk streaming response
• Usage tracking — tokens_in, tokens_out, last_tokens_in, last_tokens_out per panggilan
• Provider defaults — DeepSeek v4 flash free via OpenCode AI proxy (default)

// Contoh penggunaan di turn.rs
let result = client.chat_with_tools_non_streaming(
    &mut messages,
    Some(tool_defs),
    Some(4096),  // max_tokens
    Some(0.7),   // temperature
    None,        // abort flag
);

Tool System (infrastructure/src/tools/)

37 tool yang mengimplementasikan trait Tool dari domain:

pub trait Tool: Send + Sync {
    fn name(&self) -> &'static str;
    fn description(&self) -> &'static str;
    fn parameters(&self) -> Value;         // JSON Schema
    fn run(&self, ctx: &ToolCtx, args: &Value) -> Result<String>;
}

Kategori Tool

Kategori	Tools
File System	read, write, edit, delete, dir_list, dir_cache_update
Shell	bash, bash_interactive, bash_kill, bash_output
Git	git_operator, git_cred, git_worktree
Search	search, grep, glob, semantic_search
LSP	lsp_connect, lsp_hover, lsp_completion, lsp_definition, lsp_references, lsp_diagnostics, lsp_disconnect
Memory	remember, recall, forget
Workflow	spawn_agents, spawn_pipeline, plan, sequential_think, hive_mind
Utility	todo_write, todo_finish, pong, cd
Background	bash_bg_cancel, bash_bg_status, bash_bg_list

ToolCtx berisi:

• session_dir: PathBuf — direktori sesi aktif
• workspaces: Vec<PathBuf> — root workspace yang dibuka

Background Shell Jobs (infrastructure/src/bgbash/)

Manajemen proses shell jangka panjang:

• Spawn dengan Unix process groups (untuk kill seluruh tree)
• Output buffering — collect stdout/stderr secara async
• Cancel/status/list — kontrol via tool calls
• Progress monitoring — track state: Running, Completed, Failed

MCP Manager (infrastructure/src/mcp/)

Integrasi Model Context Protocol:

• Menggunakan crate rmcp (v2.2)
• Transport: stdio (child process) dan streamable HTTP
• list_tools() → tool discovery otomatis → registrasi ke tool harness
• Persistent connection management

LSP Integration (infrastructure/src/lsp/)

Integrasi Language Server Protocol:

• Auto-provisioner — deteksi bahasa dari file extension, start LSP server yang sesuai
• Mendukung: rust-analyzer, typescript-language-server, pyright, gopls, dan lainnya
• JSON-RPC client — typed notifications + request/response
• 7 tools LSP yang diekspose ke LLM

Persistence (infrastructure/src/persistence/)

SQLite Message Log

Session database dengan rusqlite (bundled):

• Per-session isolation
• Table: messages, sessions
• CRUD, query/filter, blob storage

Settings Repository

JsonSettingsRepository — simpan/load Settings dari settings.json:

• provider: nama provider LLM
• model: model ID
• max_tokens: override context window (default: 256k jika tidak diset)
• temperature, concise_output, dll

Memory Files

File-based memory di ~/.local/share/zesdex/memories/:

• Setiap memory = satu .md dengan frontmatter YAML
• Fields: name, description, type (user/feedback/project/reference)
• Index di MEMORY.md

Session Management (infrastructure/src/session/)

• Setiap sesi memiliki UUID, direktori sendiri di sessions/<uuid>/
• .lock file untuk cegah concurrent access
• session.json — metadata (waktu mulai, workspace, model yang dipakai)

Utils

Util	Fungsi
utils::write_osc52	Tulis teks ke clipboard via OSC52 escape sequence
Toast / ToastKind	Notifikasi sementara (Success/Warning/Error/Info/Lesson)
TurnEvent	Event dari background agent ke TUI (queue-based)
DirCache	Cache async listing direktori untuk @mention autocomplete
MentionIndex	Index file workspace untuk fuzzy autocomplete
SessionRuntime	Runtime state: messages history, usage stats, session start time

OAuth 2.0

Flow PKCE untuk provider LLM:

1. Generate code verifier + challenge
2. Open browser ke authorization URL
3. Start localhost HTTP server untuk tangkap redirect
4. Exchange code → access + refresh token
5. Simpan token di settings