Architecture chapter 01

overview/map

Lash is organized as a narrow protocol kernel plus an async host runtime. The app-facing lash facade and the CLI compose replaceable edges — providers, mode plugins, tools, dynamic tool plugins (including MCP via lash-plugin-mcp), UI extensions, persistence, tracing, and the TUI — around that core.

System Shape

Dependency direction runs from host surfaces inward to the runtime, then into the sans-IO protocol model. Providers, modes, tools, and plugins are replaceable edges around the runtime core.

Workspace topology
flowchart TD subgraph Host["Host applications"] CLI["lash-cli
TUI, setup, resume/fork, --print
(bin + lib half hosting LashConfig)"] Facade["lash (facade)
app-facing core/session/turn API"] Export["lash-export
multi-session tree → HTML / JSON"] TraceViewer["lash-trace-viewer
JSONL trace browser"] Bench["benchmark runners
CLBench, SWE-bench, LongCoT, LongMemEval"] end subgraph Runtime["Async host runtime"] L["lash-core
LashRuntime, Session, Store, PluginHost"] Env["RuntimeEnvironment
shared runtime infrastructure"] Graph["SessionGraph
durable event graph"] Read["SessionReadView
public read seam"] Tools["Tool dispatch
dynamic tools, built-ins"] Sqlite["lash-sqlite-store
concrete SQLite persistence"] Trace["lash-trace
JSONL trace records"] end subgraph Kernel["Pure protocol kernel"] S["lash-sansio
TurnMachine, Effect, Response"] LL["lashlang
parser, AST, VM, persistent REPL state"] end subgraph Extensions["Replaceable edges"] Modes["mode plugins
standard + rlm"] Providers["provider crates
OpenAI, Codex, Anthropic, Google"] Plugins["tool/plugin crates
llm_query, plan, memory, context, UI activity"] Mcp["lash-plugin-mcp
rmcp-based MCP plugin
stdio / streamable-http / sse"] Subagents["lash-subagents
spawn_agent host + RLM bridge"] end CLI --> Facade CLI --> L Facade --> L Bench --> Facade Export --> Read TraceViewer --> Trace L --> Env L --> S L --> LL L --> Graph L --> Sqlite L --> Trace Graph --> Read L --> Tools Modes --> L Providers --> L Plugins --> L Mcp --> L Subagents --> L

Current KPIs

These figures are workspace-level and exclude generated build output.

Cargo members
48Runtime core, facade, CLI/TUI, providers, plugins (including MCP), language, export, tracing, file-index, harness optimizer, examples, and benchmark crates.
Rust source
~191k LOCMeasured by line count over *.rs outside target; Rust dominates the workspace.
Rust files
~422Includes library crates, CLI/TUI, providers, tests, benches, examples, and trace/export utilities.
Execution modes
2 activestandard uses native tool calls; rlm drives work through Lashlang and can hand off to a successor session via continue_as.

Authority Boundaries

The durable source of truth is the session graph. Everything else is either an execution surface, an external transport, or a projection.

  1. Graph is durable.

    SessionGraph stores conversation records, tool events, mode events, plugin nodes, active-path metadata, checkpoint references, and replay material.

  2. Projection is derived.

    SessionReadView and ChronologicalProjection read graph state into semantic order. The CLI's UiTimeline is downstream of that — never a persistence owner.

  3. Modes own protocol behavior.

    ModePreamble, ContextProjector, and ProtocolDriverHandle decide what providers see and how model output advances a turn. RLM additionally projects read-only host bindings (e.g., history) into Lashlang scope through the ProjectedBindings seam.

  4. Tool output is projected, not raw.

    The ToolOutputBudgetPluginFactory trims oversized tool results once at the BeforeState, BeforeModel, and BeforeHistory hook sites so on-disk state, the live model prompt, and rolled-up history each see a budgeted view.

  5. Handoffs are runtime continuations.

    A turn can finish as TurnOutcome::Handoff { session_id }, which transparently activates an RLM successor with a fresh window. App hosts that use TurnBuilder::stream, run, or collect_with get the final handoff-followed TurnResult; lower-level runtime hosts can still inspect the underlying handoff chain.

  6. Runtime host capabilities are trait-shaped.

    RuntimeSessionManager implements focused plugin host traits for snapshots, tool catalogs, session tool state, session lifecycle, turns, background tasks, monitors, the session graph, prompt state, direct completion, and tracing. Public tools see these through named ToolContext capabilities, not through a general host escape hatch.

NextModules