zesdex/docs/CODEMAPS/backend.md

Backend / Service Layer

AI Provider

src/service/provider.rs (258 lines)

• LlmClient::new(api_key, model, base_url) — constructs blocking reqwest client
• chat_with_tools() — non-streaming with tool definitions
• chat_stream() — SSE streaming, returns SseParser yielding StreamEvent
• Retry logic: up to 3 attempts on transient errors, exponential backoff

OAuth

src/service/oauth/manager.rs (113 lines) + loopback.rs + pkce.rs

• PKCE flow: CodeVerifier → challenge → browser auth → loopback server → token exchange
• Configurable via app_config.json provider definitions (auth URL, token URL, scopes)

IPC / Daemon

src/ipc/ (7 files, ~300 lines total)

• Unix domain socket, length-prefixed JSON frames
• Daemon sends DaemonFrame { state: StatePayload, diff, tasks } to clients
• Clients send ClientRequest { action: Action } back
• State sync uses snapshots + binary diffs (rsync-style, not git)

Workflow Engine

src/app/workflow/engine.rs (251 lines) + script.rs

• Inline JS-style DSL executed by a lightweight runtime
• agent(), parallel(), pipeline(), phase(), log() — spawns sub-agents
• Max concurrency configurable via workflow_max_concurrency setting

Sub-Agent System

src/app/subagent/ (4 files, ~250 lines)

• run_subagent() — spawns independent agent with its own tool set & context
• Communicates via mpsc<SubagentEvent> channel (tool calls, results, completion)
• Uses LlmClient (same as main agent) with tool-use API

MCP Client

src/app/mcp/manager.rs (371 lines)

• Stdio transport: spawns child process, JSON-RPC via stdin/stdout
• HTTP transport: streaming HTTP with JSON-RPC
• Tool registration: tools/list → McpToolAdapter implements crate::tool::Tool
• Persistent child handle for stdio (reuses connection across calls)

Self-Review

src/app/review/mod.rs (437 lines)

• Post-tool execution quality check against learned lessons
• Invokes run_subagent() with reviewer prompt
• Staleness detection: skips review after N consecutive empty results

Background Bash

src/app/bgbash/ (2 files)

• spawn_bash_job() — runs sh -c in a thread, collects stdout line-by-line
• Channels: output via mpsc<String>, PID via mpsc<u32>
• Killable via PID

Gate Guard / Harness

src/app/harness.rs (127 lines)

• Harness::gate_tool_call() — verdict-based tool gating (allow/block)
• Parses LLM verdicts (JSON or plain-text)
• test_parse_verdict_* tests for 6 verdict formats