Core Contracts
These abstractions define the system more precisely than crate names do.
| Abstraction | Owner | Role |
|---|---|---|
TurnMachine, Effect, Response | lash-sansio | Pure turn state machine and host-effect protocol. |
TurnOutcome, TurnFinish, TurnStop | lash-sansio | Three-class turn result: Finished{AssistantMessage|SubmittedValue|ToolValue}, Handoff{session_id}, Stopped{Cancelled|InvalidInput|MaxTurns|ToolFailure|ProviderError|PluginAbort|RuntimeError|SubmittedError{...}|ToolError{...}}. |
ModePreamble, ContextProjector, ProtocolDriverHandle | lash-sansio + mode crates | Mode-specific prompt, request projection, and model-output interpretation. |
LashCore, LashSession, TurnBuilder | lash | App-facing facade for shared core configuration, per-conversation sessions, and semantic turn streaming. |
SessionRelation::{Root, Child, Handoff} | lash-core/src/plugin/mod.rs | How a new session relates to its parent: top-level, internal child, or successor produced by continue_as. |
StandardCreateExtras, RlmCreateExtras, RlmProjectedSeedSnapshot | lash-core/src/plugin/mode.rs + lash-rlm-types | Mode-specific session-creation payloads. RLM carries a termination policy and an optional projected-binding seed for handoffs and spawned agents. |
PluginSessionContext, SubagentSessionAuthority | lash-core/src/plugin/registry.rs | Per-session context handed to plugin factories, plus the marker that identifies a session as a subagent and tracks agent_name, depth, and parent. |
SessionStateEnvelope | lash-core/src/runtime/state.rs | Durable session-state container: graph, policy, turn index, usage, and mode turn options. |
FollowedTurn, stream_turn_following_handoffs | lash-core/src/runtime | Internal handoff-following runtime primitive used by the lash facade. App hosts normally use TurnBuilder::stream, TurnBuilder::run, or TurnBuilder::collect_with. |
SessionSnapshotHost, ToolCatalogHost, ToolStateHost, SessionLifecycleHost, SessionGraphHost, TaskHost, DirectCompletionHost | lash-core/src/plugin/mod.rs + lash-core/src/runtime/session_manager/* | Focused internal runtime-host trait split implemented by RuntimeSessionManager. Public tool code reaches the same powers through explicit ToolContext capabilities instead of receiving the bridge traits. |
TurnCommitPipeline, TurnProgress, TurnGraphOverlay | lash-core/src/runtime | Turn-scoped graph, checkpoint, usage, and read-state commit policy. |
SessionGraph, SessionReadView, ChronologicalProjection | lash-core + lash-cli/src/app/projection.rs | Durable event storage, public read seam (both in lash-core), and semantic timeline projection (CLI-side). |
RuntimePersistence, RuntimeCommit, GraphCommitDelta | lash-core/src/store.rs | Runtime persistence contract and optimistic head revision commit shape. |
Store | lash-sqlite-store | Concrete SQLite implementation for graph nodes, session heads, blobs, checkpoints, usage, tombstones, and vacuum metadata. |
ProviderHandle, ProviderComponents | lash-core/src/provider/mod.rs | Persisted provider handle split by state, auth, readiness, transport, and model policy. |
ToolDefinition, ToolSurface, ToolOutputContract | lash-sansio | Tool visibility, model schema, examples, compact docs, and dynamic return contracts. |
PluginFactory, SessionPlugin, PluginRegistrar | lash-core/src/plugin | Plugin lifecycle and hook registration for tools, prompts, modes, runtime events, and plugin actions. |
LlmToolsPluginFactory, DirectCompletionHost | lash-llm-tools + lash-core | llm_query tool registration, output-schema handling, direct completion, and usage relay. |
RlmControlToolsProvider | lash-mode-rlm/src/control_tools.rs | Mode-owned RLM control tools such as continue_as, which produces a TurnOutcome::Handoff. |
ProjectedBindings, ProjectedValue, ProjectedHostValue, ProjectedReadRequest, ProjectedReadResponse | lashlang/src/runtime/value.rs | Read-only bindings injected from the host into Lashlang scope. RLM uses this to expose history and other projected globals without copying them into VM State; assignment over a projected name is rejected at runtime. |
ToolResultProjectionHook, ToolOutputBudgetPluginFactory, ToolOutputBudgetConfig | lash-core/src/plugin/tool_result_projection_builtin.rs | Three-stage tool-output budgeter — BeforeState, BeforeModel, BeforeHistory — with ToolOutputBudgetMode::{Bytes, Tokens} limits (defaults: 16 KiB, 400 lines). |
ToolDiscoveryIndex, CatalogTool, llm_rerank_request | lash-plugin-tool-discovery/src/* | Search/load tool discovery pipeline split across catalog, provider, ranking, rerank, and schema-index modules. |
UiTimelineItem, ActivityBlock, TuiExtensions | lash-cli / lash-tui-extensions | CLI render projection, tool activity display, and host-owned surface slots. |
Plugin Registration
Plugins are assembled per session. Each plugin can contribute mode drivers, native tools, tool-surface entries, prompt text, lifecycle hooks, plugin actions, and UI activity.
Plugin contract shape
flowchart LR
Factory["PluginFactory"] --> SessionPlugin["SessionPlugin"]
SessionPlugin --> Registrar["PluginRegistrar"]
Registrar --> Mode["mode hooks
session + driver + native tools"] Registrar --> Tools["ToolProvider
ToolSurfaceContributor"] Registrar --> Prompt["PromptContributor
context transforms"] Registrar --> Runtime["runtime events
plugin actions"] Registrar --> UI["UI activity / panels"] Mode --> Session["Session"] Tools --> Session Prompt --> Session Runtime --> Session UI --> CLI["lash-cli projection"]
session + driver + native tools"] Registrar --> Tools["ToolProvider
ToolSurfaceContributor"] Registrar --> Prompt["PromptContributor
context transforms"] Registrar --> Runtime["runtime events
plugin actions"] Registrar --> UI["UI activity / panels"] Mode --> Session["Session"] Tools --> Session Prompt --> Session Runtime --> Session UI --> CLI["lash-cli projection"]
Boundary Rules
The current codebase relies on these separations staying explicit.
-
No UI vocabulary in core runtime.
UiTimelineItemand rendering stay inlash-cli. -
Provider quirks stay at provider boundary.
OpenAI-compatible schema normalization belongs in request builders, not canonical tool definitions.
-
Graph storage is not chronological policy.
Dedupe and ordering live in projections such as
ChronologicalProjection. -
Background work is handle-shaped.
Monitors, subagents, and async tool calls are rediscovered through
list_async_handles. -
Host bindings are projected, not copied.
RLM exposes
historyand any host globals to Lashlang viaProjectedBindings. They behave like ordinary names but cannot be reassigned, and the runtime prunes reserved projected names on snapshot restore so successor sessions never inherit a stale copy.