# Vegvisir Runtime Architecture

This document describes how the Rust harness currently fits together. It is intentionally system-level rather than a command dump.

## Primary Crate

The runtime lives in:

```text
vegvisir/
```

Important source areas:

```text
vegvisir/src/main.rs                 CLI entrypoint and top-level subcommands
vegvisir/src/app.rs                  TUI application shell
vegvisir/src/app/runtime.rs          TUI runtime/event integration
vegvisir/src/orchestrator.rs         Agent harness execution loop
vegvisir/src/parallelism.rs          Hardware-aware bounded worker configuration/helpers
vegvisir/src/model.rs                Model trait and scripted/local model support
vegvisir/src/provider.rs             Provider abstraction and provider selection
vegvisir/src/openai_sso.rs           OpenAI SSO integration support
vegvisir/src/tools.rs                Tool registry and tool implementations
vegvisir/src/policy.rs               Tool/risk policy behavior
vegvisir/src/sandbox.rs              Workspace and command safety support
vegvisir/src/run_artifacts.rs        Local run artifact bundle schema and writers
vegvisir/src/memory.rs               CMS-v2 integration
vegvisir/src/context.rs              Context preparation surfaces
vegvisir/src/mcp.rs                  MCP client/runtime support
vegvisir/src/lsl.rs                  Linked Skill Library parser/compiler/runtime commands
vegvisir/src/subagents.rs            Subagent supervisor and board records
vegvisir/src/bridge.rs               JSONL app-server bridge
vegvisir/src/compat_server.rs        OpenAI-compatible local server
vegvisir/src/verification.rs         Verification checks
vegvisir/src/evals.rs                Built-in eval surfaces
vegvisir/src/observability.rs        Event logging and trace surfaces
vegvisir/src/defaults/               Default prompts, agents, skills, and LSL examples
```

## CLI Entrypoint

`vegvisir/src/main.rs` defines the top-level `vegvisir` command with these current subcommands:

```text
tui
run
remember
recall
context
model-request
eval
verify
app-server
open-ai-compat-server
setup
skiller
```

Running `vegvisir` with no subcommand starts the TUI. Supplying `--prompt` or `run <goal>` executes a headless task.

Global options include provider/model/agent selection, JSON/scripted mode flags, workspace selection, max steps, run artifact output flags, and startup-only dangerous bypass mode.

## Agent Harness

The orchestrator is the part that turns a user goal into a bounded run. At a high level, a run has:

- a workspace path
- a model implementation
- a tool registry
- an optional persistent/custom agent profile
- runtime policy settings
- model/tool-call iteration limits
- memory/context support
- a checkpoint/final-answer result

The model does not directly mutate the world. It produces messages and tool-call requests; the harness decides whether a tool exists, whether it is allowed, whether approval is required, and how outputs are returned.

## Hardware-Aware Parallelism

Vegvisir Core exposes a central bounded parallelism configuration in `vegvisir/src/parallelism.rs`. The goal is to let local CPU-heavy features use the available machine without hard-coding one hardware profile or spawning unbounded threads.

Detection uses `std::thread::available_parallelism()` and defaults to reserving one core for the OS/UI when more than one core is available. The effective worker count is surfaced in `/session-status` and in the app-server `session.status` payload.

Environment overrides:

```bash
VEGVISIR_MAX_WORKERS=12        # explicit worker ceiling
VEGVISIR_MAX_WORKERS=auto      # hardware-aware default
VEGVISIR_RESERVED_CORES=2      # reserve cores from the auto calculation
```

The helper `run_parallel_ordered` is intended for deterministic local work where inputs can be processed concurrently but output order must remain stable. SQLite writes, session mutation, approvals, provider calls, and dependent tool-call chains should still remain serialized unless a feature adds explicit safe batching.

## TUI Runtime

The TUI is the normal operator interface. It provides:

- streaming provider output
- Markdown rendering
- full-width transcript body for readable selection/copy
- command palette and slash command selection
- workspace switching
- provider/model selection
- approvals modal
- transcript search
- activity/tool log surfaces
- tool inventory and command allow-list management
- context/memory/system prompt inspectors
- subagent board visibility

The TUI runtime is also responsible for surfacing important operational events in the transcript so tool work and child-agent work are not invisible.

## Headless Mode

Headless mode is useful for scripted tasks:

```bash
vegvisir --workspace /path/to/project run "Summarize this repository"
vegvisir --workspace /path/to/project --artifacts run "Summarize this repository"
vegvisir --workspace /path/to/project --json --artifacts run "Summarize this repository"
vegvisir --workspace /path/to/project --artifacts eval golden
vegvisir --workspace /path/to/project --artifacts verify runtime
```

It should still respect workspace scope, provider configuration, tool policies, memory behavior, and max-step bounds. Use headless mode for automation where an interactive approvals UI is not needed or where policy is already configured for the run. When `--artifacts` or `--artifact-dir` is used, JSON headless output includes the emitted `run_id` and `artifact_dir`. Artifact-enabled scripted and provider headless failures finalize the bundle with `manifest.json` status `failed` and a `failure.json` recoverable failure record.


## Run Artifact Bundles

Run artifact bundles are local audit/evidence directories for individual Vegvisir turns. They are intended to make headless and TUI work reviewable without mixing runtime evidence into durable CMS memory or source control.

Default location:

```text
<workspace>/.vegvisir/runs/<run-id>/
```

Headless `run`, `eval`, and `verify` commands write bundles when `--artifacts` is set or when `--artifact-dir <root>` is provided. `--artifact-dir` changes the root and writes the bundle as `<root>/<run-id>/`. TUI sends create and finalize turn artifacts automatically in the workspace run directory.

Current emitted files include:

```text
manifest.json            schema version, run/session identity, provider/model/agent, status, timestamps, path registry
request.json             redacted prompt/request metadata
context.md               redacted CMS/ECM-prepared provider prompt context
context-sources.json     redacted prompt-cache block/capsule/source metadata for the prepared context
memory-used.json         redacted memory/source-id evidence derived from the prepared prompt envelope
memory-written.json      redacted completion memory writeback ids/status when captured
approvals.json           redacted pending approval evidence, or no_approvals/unavailable status
subagents.json           redacted subagent board snapshot, or no_subagents/unavailable status
verification.json        redacted verification/test evidence, or no_verification/unavailable status
result.md                redacted final answer when available
provider-events.jsonl    redacted provider/runtime stream events
tool-events.jsonl        redacted tool start/end events
file-changes.json        redacted git status evidence captured at bundle finalization
diff.patch               redacted tracked staged/unstaged git diff evidence captured at bundle finalization
failure.json             recoverable or fatal worker failure details when a turn fails
```

Provider/TUI/headless `run` bundles include prepared-prompt context artifacts. Deterministic `eval` and `verify` bundles may omit `context.md`, `context-sources.json`, and `memory-used.json` because they do not send a provider prompt.

`memory-used.json` records the memory IDs, block/capsule IDs, prompt cache key, and token counts that came from the CMS/ECM prepared prompt envelope; it avoids storing full memory bodies beyond the already-redacted context artifact. `memory-written.json` records completion writeback status and memory IDs from successful headless runs and TUI turns, or an unavailable/no-write status when writeback cannot be captured. `approvals.json` records the pending approval queue snapshot for the run, using redacted/summarized arguments such as command arrays, file paths, and content length rather than raw file content. `verification.json` records observed verification/test tool events when available, otherwise it records `no_verification` for completed runs with no captured checks or `unavailable` for runs that ended before verification evidence could be captured. `subagents.json` records the current durable subagent board snapshot at bundle finalization, including task status, bounded scope/budget, captured final answer/error, observability, and file-change summaries when available. Artifact writers apply best-effort redaction to secret-like JSON keys and common token-shaped text before persisting files, but artifacts should still be treated as local operational evidence rather than a credential store.

## App-server Bridge

The app-server bridge is a JSONL protocol for desktop shells or external clients. It is not the model provider. It is a control surface around a Vegvisir session.

Representative methods include:

- `initialize`
- `session.start`
- `session.messages`
- `session.exportMarkdown`
- `turn.send`
- `command.run`
- `session.status`
- `tools.list`
- `providers.list`
- `models.list`
- `agents.list`
- `approvals.list`
- `approvals.approveOnce`
- `approvals.approveSession`
- `approvals.edit`
- `approvals.deny`
- `diff.current`
- `memory.status`
- `system.prompt`
- `system.prompt.set`
- `shutdown`

See [overlay integration](overlay-integration.md) for the protocol details.

## Provider Flow

Provider/model selection is runtime configuration. The harness can use configured provider adapters and supports provider/model inspection surfaces.

Provider-sensitive behavior:

- streaming when available
- model discovery where supported
- OpenAI SSO where configured
- OpenAI-compatible local/server endpoints
- HBSE-backed provider credential access when configured
- scripted/local models for deterministic tests

The provider is responsible for generation. Vegvisir is responsible for assembling context, enforcing policy, executing tools, recording events, and reporting verification.

## Tool Registry

The tool registry is the model’s controlled interface to the workspace and environment. Tool categories include:

- filesystem reads/writes/listing within the workspace
- bounded shell commands and tests
- git/diff inspection
- CMS-v2 memory recall/write operations
- context/model-request helpers
- Skiller compile/validate/route/load/forge helpers
- MCP tool calls
- verification/eval/trace helpers
- subagent delegation

Tool behavior should be evidence-forward: important reads, writes, commands, errors, and verification results should be visible to the operator.

## Command And Filesystem Safety

Filesystem tools are workspace-scoped and hardened against path traversal and unsafe symlink escapes. Shell commands are executable allow-listed, timeout-bound, output-limited, and optionally wrapped by the command OS sandbox. Risky operations, non-allow-listed commands, and network-like command requests may require approval.

Command sandbox environment controls:

```bash
VEGVISIR_COMMAND_SANDBOX=path|none|bwrap|strict-bwrap
VEGVISIR_COMMAND_NETWORK=inherit|disable|require-approval
VEGVISIR_COMMAND_WRITABLE_PATHS=/path/a:/path/b
VEGVISIR_COMMAND_READONLY_PATHS=/path/a:/path/b
VEGVISIR_COMMAND_HIDDEN_PATHS=/path/a:/path/b
```

Dangerous bypass mode exists for trusted high-risk sessions but can only be selected at startup. It bypasses approvals, command allow-lists, active-agent tool allow-lists, USRL tool gates, workspace file sandboxing, and command sandbox wrapping.

Preserve-user-work rule: do not revert, delete, overwrite, reset, or discard unrelated user changes unless explicitly instructed.

See [Command sandboxing and approvals](command-sandboxing-and-approvals.md) for operator-level details.

## Memory Flow

Memory has three different responsibilities:

1. CMS-v2 durable storage and retrieval.
2. ECM/context preparation for the active turn.
3. Provider prompt use during generation.

The boundary is important: long-term storage is not the same thing as dumping every memory into every prompt. Vegvisir should recall relevant project memory first and use global memory only when cross-project context is clearly relevant.

## Skills And LSL Runtime

The runtime supports built-in skills and filesystem skills. LSL adds structured libraries with subskills, routing metadata, load blocks, dependency links, policy inheritance, eval hooks, traces, detection, curation, and promotion/archive operations.

Important TUI commands include:

```text
/skills status
/skills compile
/skills route <query>
/skills load [--tokens N] <query-or-subskill>
/skills explain <query-or-subskill>
/skills trace
/skills detect
/skills curate
/skills forge <library.subskill> | <title> | <summary> | <body> [| tags=a,b]
/skills eval [target-or-eval]
/skills promote <library.subskill>
/skills archive <library.subskill>
/skills patch <library.subskill> | <operation> | <path> | <value>
/skills invoke <subskill-id> [json-input]
```

Compiled artifacts live under `.vegvisir/compiled` in the workspace. LSL source discovery is sorted deterministically, and source hashing/compilation uses the Core `run_parallel_ordered` helper so large skill libraries can fan out across the configured worker budget without changing final registry order.

## Subagent Runtime

The subagent supervisor supports child task records and a board file. Subagent records include identity, workspace, goal, file scope, work budget, status, timestamps, checkpoint, final answer, and error. Active file scopes are checked so parallel workers do not own overlapping file sets.

Subagent events include:

- `subagent.queued`
- `subagent.started`
- `subagent.completed`
- `subagent.failed`
- `subagent.cancelled`

Subagents are best for bounded independent tasks. Do not delegate credential handling, destructive actions, ambiguous external side effects, or broad unsupervised implementation across overlapping files. Use `/subagents list`, `/subagents show <id-or-name>`, `/subagents cancel <id-or-name>`, and `/subagents policy` to inspect and manage the board. See [Subagent delegation](subagent-delegation.md).

## Verification Surfaces

Use `vegvisir verify` for runtime/environment checks:

```bash
vegvisir verify all --workspace /path/to/project
vegvisir verify auth --workspace /path/to/project
vegvisir verify mcp --workspace /path/to/project
vegvisir verify runtime --workspace /path/to/project
vegvisir verify memory --workspace /path/to/project
```

Use `vegvisir eval` for built-in eval scopes or eval files:

```bash
vegvisir eval all
vegvisir eval memory
vegvisir eval security
vegvisir eval --file ./path/to/eval.json
```

For source changes, run focused tests and usually at least:

```bash
cargo check --workspace
```

For release-quality runtime changes, run:

```bash
cargo test --workspace -- --test-threads=1
```

## Runtime State Locations

Common state roots:

```text
${XDG_DATA_HOME:-$HOME/.local/share}/vegvisir/    user-level Vegvisir state and CMS database
<workspace>/.vegvisir/                           workspace-local compiled skills and run artifacts
~/.vegvisir/tools                                installed component runtimes and wrappers
```

Do not commit local runtime artifacts, databases, generated caches, downloaded browser state, provider credentials, or auth storage.

## Development Notes

- Keep command help docs generated or checked against current CLI behavior when commands change.
- Keep system docs grounded in source paths and current component responsibilities.
- Prefer adding architecture docs over bloating README.
- If `plan.md` is used locally, keep it ignored and untracked.
