HLVM Agent System — Architecture & Reference

           ┌─────────────────────────────────┐
           │       CLI / HTTP / REPL          │
           │  ask.ts · chat.ts · repl.ts      │
           └──────────────┬──────────────────┘
                          │
           ┌──────────────▼──────────────────┐
           │   runAgentQuery()  [SSOT]        │
           │   agent-runner.ts                 │
           │   - Session setup                 │
           │   - Policy + tool init             │
           │   - Engine resolution              │
           └──────────────┬──────────────────┘
                          │
           ┌──────────────▼──────────────────┐
           │   createAgentSession()            │
           │   session.ts                      │
           │   - System prompt compilation      │
           │   - MCP tool loading               │
           │   - Context budget resolution      │
           │   - Memory injection               │
           └──────────────┬──────────────────┘
                          │
┌─────────────────────────▼───────────────────────────┐
│              runReActLoop()                          │
│              orchestrator.ts                         │
│                                                      │
│   ┌─────────────────────────────────────────────┐   │
│   │  for each iteration (max 20):               │   │
│   │   1. Call LLM (with retry + timeout)        │   │
│   │   2. Parse tool calls from response         │   │
│   │   3. Execute tools (parallel by default)    │   │
│   │   4. Format results → add to context        │   │
│   │   5. Inject memory recall if applicable     │   │
│   │   6. Check stopping conditions              │   │
│   └─────────────────────────────────────────────┘   │
│                                                      │
└──────────────────────┬──────────────────────────────┘
                       │
           ┌───────────▼────────────┐
           │  AgentRunnerResult      │
           │  - Final text response  │
           │  - Stats (tokens, time) │
           │  - Citations metadata   │
           └────────────────────────┘

src/hlvm/agent/
├── agent-runner.ts              # Main entry: runAgentQuery()
├── agent-registry.ts            # Built-in + custom agent profiles
├── constants.ts                 # Limits, timeouts, model tiers
├── engine.ts                    # AgentEngine interface + singleton
├── engine-sdk.ts                # Vercel AI SDK v6 engine impl
├── error-taxonomy.ts            # Error classification
├── hooks.ts                     # Lifecycle hooks runtime
├── llm-integration.ts           # System prompt compilation
├── orchestrator.ts              # ReAct loop + AgentUIEvent type
├── orchestrator-state.ts        # Loop state types
├── orchestrator-tool-execution.ts
├── orchestrator-tool-formatting.ts
├── orchestrator-llm.ts
├── orchestrator-response.ts
├── registry.ts                  # Tool registry (SSOT)
├── session.ts                   # AgentSession creation + reuse
├── mcp/
│   ├── sdk-client.ts            # MCP SDK adapter
│   ├── config.ts                # Server config loading
│   ├── tools.ts                 # MCP tool registration
│   └── oauth.ts                 # OAuth2 for MCP servers
src/hlvm/prompt/
├── compiler.ts                  # Prompt compilation pipeline
├── sections.ts                  # Section renderers (role, rules, routing, etc.)
├── instructions.ts              # Instruction hierarchy
├── types.ts                     # PromptMode, InstructionHierarchy
src/hlvm/memory/
├── db.ts                        # SQLite + FTS5 schema
├── facts.ts                     # Fact CRUD + search
├── entities.ts                  # Entity tracking
├── retrieve.ts                  # Hybrid retrieval
├── invalidate.ts                # Auto-invalidation
├── manager.ts                   # loadMemoryContext()
├── tools.ts                     # memory_write/search/edit
├── store.ts                     # MEMORY.md + journal I/O
├── explicit.ts                  # Explicit memory operations
├── pipeline.ts                  # Memory pipeline orchestration
├── policy.ts                    # Memory policy configuration

hlvm ask "refactor the auth module"
hlvm ask "what does session.ts do" --model anthropic/claude-sonnet-4-20250514
hlvm ask --verbose --json "create hello.txt"

// src/hlvm/agent/agent-runner.ts
export async function runAgentQuery(
  options: AgentRunnerOptions,
): Promise<AgentRunnerResult>;

First run → createAgentSession() → runReActLoop() → return session ID

Second run with --resume <id>:
  → reuseSession(existingSession)
    → Replace stale memory with fresh retrieval
    → Skip `# Your Memory` marker during message rehydration
    → Reuse LLM + context manager
  → runReActLoop()

for iteration = 1 to MAX_ITERATIONS (20):
  1. maybeInjectMemoryRecall()     — retrieve relevant memory facts
  2. maybeInjectReminder()          — safety/routing reminders (tier-aware)
  3. LLM call with retry (max 3)
  5. Parse tool calls from response
  6. Execute tools (parallel by default)
  7. Format results, add to context
  8. Derive runtime phase: researching | editing | verifying | completing
  9. Apply adaptive tool phase filtering (narrow available tools based on phase)
  10. Check stopping: max tokens, max iterations, quality threshold

registerTool(name, metadata); // Add a tool
registerTools(entries); // Bulk add
unregisterTool(name); // Remove (MCP cleanup)
getTool(name); // Lookup by name
getAllTools(); // All registered tools
getToolsByCategory(); // Returns all tools grouped by category
searchTools(query, options); // Fuzzy search for tool_search
resolveTools(allowlist, denylist, ownerId); // Build filtered set

interface ToolMetadata {
  fn: ToolFunction;
  description: string;
  args: Record<string, string>; // arg name → description
  argAliases?: Record<string, string>;
  returns?: Record<string, string>; // return field → description
  safetyLevel?: "L0" | "L1" | "L2";
  safety?: string; // additional safety info text
  category?:
    | "read"
    | "write"
    | "search"
    | "shell"
    | "git"
    | "web"
    | "data"
    | "meta"
    | "memory";
  replaces?: string; // shell command this tool replaces (e.g., "cat/head/tail")
  skipValidation?: boolean; // for dynamic tools with unknown schemas
  formatResult?: (result: unknown) => FormattedToolResult | null;
  terminalOnSuccess?: boolean; // standalone success = end turn
}

# Allow specific tools (repeatable)
hlvm ask --allowedTools write_file --allowedTools edit_file "fix bug"

# Deny specific tools (repeatable)
hlvm ask --disallowedTools shell_exec "analyze code"

# Combine with permission modes
hlvm ask --permission-mode dontAsk --allowedTools write_file "generate docs"

type ModelTier = "weak" | "mid" | "frontier";

classifyModelTier(modelInfo, isFrontier) → ModelTier
  // frontier: API-hosted (anthropic/openai/google/claude-code) OR context ≥ 128K
  // weak: local model with <13B params
  // mid: everything else

computeTierToolFilter(tier) → { allowlist, denylist }
  // weak: restricted to WEAK_TIER_CORE_TOOLS (read, list, search, shell basics)
  // mid/frontier: full access

const PROFILE_ALIASES = {
  "general-purpose": "general",
  "generalist": "general",
};

---
name: reviewer
description: Code review specialist
tools:
  - read_file
  - search_code
  - find_symbol
  - get_structure
temperature: 0.1
instructions: Focus on security, performance, and code quality.
---

## Review Guidelines

When reviewing code, check for:

- OWASP Top 10 vulnerabilities
- Performance bottlenecks
- Code style violations

interface AgentEngine {
  createLLM(config: AgentLLMConfig): LLMFunction;
  createSummarizer(): (text: string) => Promise<string>;
}

// src/hlvm/prompt/compiler.ts
compilePrompt(input: PromptCompilerInput): CompiledPrompt

// src/hlvm/prompt/types.ts
interface InstructionHierarchy {
  global: string; // Content from ~/.hlvm/HLVM.md (required)
  project: string; // Content from <workspace>/.hlvm/HLVM.md (required, empty if untrusted)
  projectPath?: string; // Workspace path if project instructions were attempted
  trusted: boolean; // Whether the workspace is trusted
}

## Tool Routing
| Instead of... | Use... | Why |
|---------------|--------|-----|
| shell grep    | search_code | Structured results, respects gitignore |
| curl          | fetch_url   | Handles auth, rate limits |

memory_write → SQLite DB (facts, entities, relationships) → MEMORY.md (projection)
                     ↕
              FTS5 full-text index

inferMcpSafetyLevel(toolName, description?) → "L0" | "L1" | "L2"
  // Checks combined toolName + description text:
  // L2: matches MCP_MUTATING_RE (write, create, update, delete, remove, destroy, execute, run, etc.)
  // L0: matches MCP_READ_ONLY_RE (read, list, get, fetch, search, find, etc.)
  // L1: default for unrecognized tools (neither read-only nor mutating pattern matched)

type ConversationItem =
  | UserItem // User input
  | AssistantItem // Agent text response
  | ThinkingItem // Reasoning/planning bubbles
  | ToolGroupItem // Grouped tool call results
  | ErrorItem // Error messages
  | InfoItem // Generic info
  | MemoryActivityItem; // Memory recall/write activity

Orchestrator (runReActLoop)
  │ emits AgentUIEvent via onAgentEvent callback
  │
  ├─► CLI: agent-transcript-state.ts reduces events → ConversationItem[]
  │         ConversationPanel renders items
  │
  ├─► HTTP: Streamed as NDJSON { type: "agent_event", event: {...} }
  │
  └─► JSON mode: --json flag outputs raw NDJSON stream

classifyError(error) → ErrorClass

tests/unit/agent/
├── llm-integration.test.ts      # Prompt compilation tests
├── sdk-runtime.test.ts          # SDK message consolidation tests
├── error-taxonomy.test.ts       # Error classification tests

tests/unit/repl/
├── footer-hint.test.ts          # 23 tests (footer rendering)
├── shell-chrome.test.ts         # Shell footer tests

tests/unit/prompt/
├── compiler.test.ts             # Prompt compilation pipeline tests
├── instructions.test.ts         # Instruction hierarchy tests

tests/unit/memory/
├── memory.test.ts               # 47 tests (DB, facts, retrieval, invalidation)

# Full suite
deno task test:unit

# SSOT compliance
deno task ssot:check

~/.hlvm/                        # Data root
~/.hlvm/HLVM.md                 # Global instructions
~/.hlvm/trusted-workspaces.json # Trust registry
~/.hlvm/memory/                 # Memory database
<workspace>/.hlvm/HLVM.md       # Project instructions
<workspace>/.hlvm/agents/       # Custom agent profiles