Valstorm Logo
ValstormDocs
AI and Agents•v2.0.0•3 min read

vsagent Architecture Deep Dive

Architectural deep dive into vsagent: ReAct internals, LSP diagnostic interceptors, multi-tenant platform kernels, and cognitive swarms.

For AI architects, compiler engineers, and systems developers, this document breaks down the internal architecture, design trade-offs, and execution pipelines of the Valstorm Agent Runtime (vsagent).

1. Architectural Comparison: vsagent vs. OpenCode vs. Claude Code

DimensionValstorm Agent (vsagent)OpenCodeClaude Code
Execution KernelCustom zero-overhead Python ReAct engine with streaming SSE and in-process subagents.Node/TypeScript TUI harness.Proprietary Anthropic CLI harness.
Model Routing3-Tier Cognitive Router (Gemini, Claude, OpenAI, Groq, Ollama).Proxies / Ollama.Anthropic Claude models only.
Compiler FeedbackIn-Memory LSP Interceptor (core/lsp/) for Python, TypeScript, Go, and YAML.LSP server process.Shell exit codes only.
Enterprise Platform CUDNative Platform Kernel: Direct SQL dialect, MongoDB aggregations, and VFS vectors.None (filesystem only).None (filesystem only).
State & RollbacksDual State Engine: SQLite FTS5 persistence + Git tree hash snapshots (/undo).SQLite state + Git snapshots.Git diff checkpoints.
Procedural Knowledge170+ Indexed SOP Skills (skill_view, skill_list) injected on demand.Generic system prompts.Prompt directives (CLAUDE.md).

2. In-Memory LSP Diagnostic Pipeline

Most coding agents rely on slow shell execution loops (pytest, npm test) to discover syntax errors. vsagent embeds an asynchronous LSP diagnostic interceptor directly inside file write tools:

┌────────────────────────┐ │ Agent calls patch_file│ └───────────┬────────────┘ │ ▼ ┌────────────────────────┐ │ Atomic Write to Disk │ └───────────┬────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Async Diagnostic Pipeline (core/lsp/) │ │ • .py: ast.parse() [0ms] + ruff check [--concise] │ │ • .ts/.tsx: tsc --noEmit (workspace tsconfig resolution) │ │ • .go: go vet (module-aware) │ │ • .json/.yaml: in-process schema & safe-load parsers │ └───────────────────────────┬─────────────────────────────────┘ │ ┌───────────────┴───────────────┐ ▼ ▼ [Errors Detected] [0 Errors Found] Appends formatted diagnostics Returns clean diff only forcing Turn 2 self-correction (zero context pollution)

3. Transactional Git Trees & SQLite FTS5 State

vsagent persists all state across two complementary storage layers:

  1. Session & Fact Storage (storage.db & memories.json):
    • SQLite with FTS5 full-text indexing across historical conversation turns (session_search).
    • Declarative long-term memory facts (user preferences vs. memory codebase notes).
  2. Transactional Git Snapshot Engine (core/snapshot.py):
    • Before mutating files, GitSnapshotManager generates an internal Git tree hash (git stash create).
    • When /undo is triggered, the working tree is restored to the exact pre-turn snapshot, and conversation history is trimmed in SQLite without data corruption.