lash/
lib.rs

1//! App-facing embedding facade for Lash.
2//!
3//! `lash` is intentionally a small layer above the lower-level
4//! `lash-core` runtime crate. Host applications own providers, persistence,
5//! app state, HTTP protocols, auth, and frontend streaming; this crate
6//! owns only the ergonomic core/session/turn API.
7//!
8//! Every public name has exactly one home. The crate root carries the daily
9//! core/session/turn path; each domain module ([`tools`], [`persistence`],
10//! [`plugins`], [`observe`], [`host_events`], ...) carries its own
11//! vocabulary. [`prelude`] mirrors the crate root exactly.
12
13pub mod control;
14mod core;
15mod error;
16mod mode;
17mod plugin_binding;
18mod prompt_layer;
19mod session;
20mod support;
21#[cfg(test)]
22mod tests;
23pub mod turn;
24pub mod usage;
25
26pub use crate::control::{
27    AdvancedToolsControl, HostEventsControl, PluginActions, SessionCommandsControl, ToolsControl,
28    TriggersControl,
29};
30pub use crate::core::{LashCore, LashCoreBuilder, SessionDeleteReport};
31pub use crate::error::{EmbedError, Result};
32pub use crate::mode::{ModeId, ModePreset};
33pub use crate::plugin_binding::PluginBinding;
34pub use crate::prompt_layer::PromptLayerSink;
35pub use crate::session::{
36    EnqueueTurnBuilder, LashSession, ObservableSession, SessionBuilder, SessionConfigPatch,
37};
38pub use crate::turn::{
39    QueuedTurnBuilder, TurnActivityFanout, TurnBuilder, TurnOutput, TurnResult, TurnStream,
40    message_role, message_text,
41};
42pub use lash_core::{
43    InputItem, ModelLimits, ModelSpec, PluginStack, SessionCommand, SessionCommandReceipt,
44    SessionSpec, TurnActivity, TurnActivityId, TurnActivitySink, TurnEvent, TurnInput,
45};
46/// Cooperative cancellation handle accepted by
47/// [`TurnBuilder::cancel`](crate::TurnBuilder::cancel); re-exported so
48/// embedders cancel turns without depending on `tokio-util` themselves.
49pub use tokio_util::sync::CancellationToken;
50
51/// The prelude is exactly the crate root: `use lash::prelude::*;` brings in
52/// the daily core/session/turn vocabulary and nothing from the domain
53/// modules.
54pub mod prelude {
55    pub use crate::{
56        AdvancedToolsControl, EmbedError, EnqueueTurnBuilder, HostEventsControl, InputItem,
57        LashCore, LashCoreBuilder, LashSession, ModeId, ModePreset, ModelLimits, ModelSpec,
58        ObservableSession, PluginActions, PluginBinding, PluginStack, PromptLayerSink,
59        QueuedTurnBuilder, Result, SessionBuilder, SessionCommand, SessionCommandReceipt,
60        SessionCommandsControl, SessionConfigPatch, SessionDeleteReport, SessionSpec, ToolsControl,
61        TriggersControl, TurnActivity, TurnActivityFanout, TurnActivityId, TurnActivitySink,
62        TurnBuilder, TurnEvent, TurnInput, TurnOutput, TurnResult, TurnStream, message_role,
63        message_text,
64    };
65}
66
67/// Session observation: cursors, resumable event streams, and live replay
68/// recovery for host frontends. Entry point: [`LashSession::observe`] /
69/// [`ObservableSession`].
70pub mod observe {
71    pub use lash_core::{
72        SessionCursor, SessionObservation, SessionObservationEvent, SessionObservationEventPayload,
73        SessionObservationSubscription, SessionProcessEventKind, SessionQueueEventKind,
74        SessionResume, SessionRevision,
75    };
76}
77
78/// Host events and triggers: declaring event sources, emitting occurrences,
79/// and inspecting trigger subscriptions. Entry points:
80/// [`LashCore::host_events`] and [`LashSession::triggers`].
81pub mod host_events {
82    pub use lash_core::{
83        HostEvent, HostEventEmitReport, HostEventOccurrenceRequest, TriggerRegistration,
84        TriggerSourceType, TriggerSubscriptionFilter, TriggerTargetSummary,
85        empty_host_event_source_key,
86    };
87}
88
89pub mod tools {
90    pub use lash_core::{
91        PreparedToolCall, ToolActivation, ToolAgentSurface, ToolArgumentProjectionPolicy,
92        ToolAvailability, ToolAvailabilityConfig, ToolCall, ToolCallOutput, ToolCallRecord,
93        ToolContext, ToolContract, ToolDefinition, ToolHostEventControl, ToolManifest,
94        ToolOutputContract, ToolPrepareCall, ToolPrepareContext, ToolProvider, ToolResult,
95        ToolScheduling, ToolSourceHandle,
96    };
97    pub use lash_core::{ToolRestoreReport, ToolState, ToolStateEntry};
98    /// Author a fixed-tool provider without hand-rolling `tool_manifests` /
99    /// `resolve_contract`: supply the [`ToolDefinition`]s once and an
100    /// [`StaticToolExecute`] for behavior.
101    pub use lash_tool_support::{StaticToolExecute, StaticToolProvider};
102}
103
104pub mod direct {
105    pub use lash_core::llm::types::{
106        LlmAttachment, LlmEventSender, LlmOutputPart, LlmTerminalReason, LlmUsage,
107    };
108    pub use lash_core::{
109        DirectCompletion, DirectJsonSchema, DirectLlmClient, DirectLlmCompletion, DirectLlmError,
110        DirectMessage, DirectOutputSpec, DirectPart, DirectRequest, DirectRole, LlmResponse,
111        TokenUsage,
112    };
113}
114
115pub mod persistence {
116    pub use lash_core::FileAttachmentStore;
117    pub use lash_core::runtime::{
118        DeliveryPolicy, InMemorySessionStore, InMemorySessionStoreFactory, MergeKey,
119        QueuedWorkBatch, QueuedWorkBatchDraft, QueuedWorkClaim, QueuedWorkClaimBoundary,
120        QueuedWorkCompletion, QueuedWorkItem, QueuedWorkPayload, RuntimeSessionState,
121        SessionStoreCreateRequest, SessionStoreFactory, SlotPolicy,
122    };
123    pub use lash_core::store::queued_work;
124    pub use lash_core::store::{
125        GraphCommitDelta, HydratedSessionCheckpoint, PersistedSessionRead, RuntimeCommit,
126        RuntimeCommitResult, RuntimeTurnCommitStamp, SessionCheckpoint, SessionHead,
127        SessionHeadMeta, load_persisted_session_state, load_persisted_session_state_active_path,
128    };
129    pub use lash_core::{AttachmentStore, InMemoryAttachmentStore};
130    pub use lash_core::{
131        BlobRef, GcReport, PersistedSessionConfig, PersistedTurnState, ProtocolEvent,
132        RuntimePersistence, SessionEventRecord, SessionGraph, SessionMeta, SessionNodeRecord,
133        SessionReadScope, SessionReadView, SessionRelation, StoreError, TokenLedgerEntry,
134        VacuumReport,
135    };
136    pub use lash_core::{InMemoryLashlangArtifactStore, LashlangArtifactStore};
137}
138
139pub mod plugins {
140    pub use crate::plugin_binding::PluginBinding;
141    pub use lash_core::PluginDirective;
142    pub use lash_core::plugin::{
143        AfterToolCallHook, AfterTurnHook, AssistantResponseHook, AssistantResponseHookContext,
144        AssistantResponseTransform, AssistantStreamHook, AssistantStreamHookContext,
145        AssistantStreamTransform, BeforeToolCallHook, BeforeTurnHook, CheckpointHook,
146        CheckpointHookContext, CompactionContext, ContextCompaction, ContextCompactor,
147        ContextError, PluginSpecBuilder, StaticPluginFactory, ToolCallHookContext,
148        ToolResultHookContext,
149    };
150    pub use lash_core::{
151        PluginError, PluginFactory, PluginHost, PluginMessage, PluginRegistrar, PluginRuntimeEvent,
152        PluginSession, PluginSessionContext, PluginSpec, PluginSpecFactory, PromptHookContext,
153        SessionPlugin, ToolSurfaceContribution, ToolSurfaceOverride, TurnHookContext,
154        TurnResultHookContext,
155    };
156    pub use lash_plugin_tool_output_budget::{
157        ToolOutputBudgetConfig, ToolOutputBudgetMode, ToolOutputBudgetPluginFactory,
158        tool_output_budget_stack as runtime_plugin_stack,
159    };
160}
161
162pub mod modes {
163    pub use crate::mode::{RlmSessionBuilderExt, RlmTurnBuilderExt};
164    pub use lash_protocol_rlm::{
165        LashlangAbilities, LashlangLanguageFeatures, LashlangSurface, NamedDataType,
166        ResourceCatalog, RlmProtocolPluginConfig, TypeExpr, TypeField, format_type_expr,
167    };
168    pub use lash_rlm_types::RlmFinalAnswerFormat;
169}
170
171pub mod messages {
172    pub use lash_core::MessageRole;
173}
174
175pub mod remote {
176    pub use lash_remote_protocol::{
177        REMOTE_PROTOCOL_VERSION, RemoteAssistantOutput, RemoteAssistantOutputState,
178        RemoteAttachmentRef, RemoteCausalRef, RemoteDiagnostic, RemoteExecutionSummary,
179        RemoteGenerationOptions, RemoteHostEventEmitReport, RemoteHostEventOccurrenceRecord,
180        RemoteHostEventOccurrenceRequest, RemoteInputItem, RemoteLiveReplayGap,
181        RemoteLiveReplayGapReason, RemoteLlmAttachment, RemoteLlmContentBlock, RemoteLlmMessage,
182        RemoteLlmOutputPart, RemoteLlmOutputSpec, RemoteLlmRequest, RemoteLlmRequestMetadata,
183        RemoteLlmResponse, RemoteLlmRole, RemoteLlmTerminalReason, RemoteLlmToolChoice,
184        RemoteLlmToolSpec, RemoteModelIntent, RemotePromptBuiltin, RemotePromptContribution,
185        RemotePromptContributionGate, RemotePromptLayer, RemotePromptSlot, RemotePromptSlotLayer,
186        RemotePromptTemplate, RemotePromptTemplateEntry, RemotePromptTemplateSection,
187        RemoteProtocolError, RemoteProtocolTurnOptions, RemoteProviderMetadata,
188        RemoteProviderReasoningReplay, RemoteProviderReplayMeta, RemoteResponseTextMeta,
189        RemoteSchemaProjectionOverride, RemoteSessionCursor, RemoteSessionObservationEvent,
190        RemoteSessionObservationEventPayload, RemoteSessionProcessEventKind,
191        RemoteSessionQueueEventKind, RemoteTokenLedgerEntry, RemoteToolActivation,
192        RemoteToolAgentSurface, RemoteToolArgumentProjectionPolicy, RemoteToolAvailability,
193        RemoteToolCallOutcome, RemoteToolCallRequest, RemoteToolCallResponse,
194        RemoteToolCallSummary, RemoteToolGrant, RemoteToolOutputContract, RemoteToolRegistry,
195        RemoteToolRetryPolicy, RemoteToolScheduling, RemoteTriggerRegistration,
196        RemoteTriggerSubscriptionFilter, RemoteTriggerTargetSummary, RemoteTurnActivity,
197        RemoteTurnEvent, RemoteTurnFinish, RemoteTurnInput, RemoteTurnIssue, RemoteTurnOutcome,
198        RemoteTurnRequest, RemoteTurnResult, RemoteTurnStatus, RemoteTurnStop,
199        RemoteTurnUsageSummary, RemoteUsage, assert_remote_tool_registry_reopenable,
200        ensure_protocol_version,
201    };
202}
203
204pub mod process {
205    pub use crate::control::ProcessControl;
206    pub use lash_core::{
207        ObservedProcess, ObservedProcessEvent, ObservedWorkItem, ProcessAwaitOutput,
208        ProcessCancelAbility, ProcessCancelAllRequest, ProcessCancelRequest, ProcessCancelSource,
209        ProcessCancelSummary, ProcessDefinitionSummary, ProcessEvent, ProcessEventAppendRequest,
210        ProcessEventAppendResult, ProcessEventType, ProcessExecutionContext, ProcessExternalRef,
211        ProcessHandleDescriptor, ProcessHandleGrant, ProcessHandleSummary, ProcessInput,
212        ProcessLease, ProcessLeaseCompletion, ProcessLifecycleStatus, ProcessListFilter,
213        ProcessListMode, ProcessOpScope, ProcessRecord, ProcessRegistration, ProcessRegistry,
214        ProcessRunHandle, ProcessRuntimeHost, ProcessScope, ProcessScopeId, ProcessService,
215        ProcessSessionDeleteReport, ProcessStartOptions, ProcessStartRequest, ProcessStatus,
216        ProcessStatusFilter, ProcessTerminalState, ProcessWake, ProcessWakeDedupeKey,
217        ProcessWakeDelivery, ProcessWakeSpec, ProcessWorkDriver, ProcessWorkObserver,
218        ProcessWorkPoke, ProcessWorkRunner, ProcessWorkSnapshot, lashlang_process_event_types,
219    };
220}
221
222pub mod durability {
223    pub use lash_core::{
224        DurableProcessWorker, DurableProcessWorkerConfig, EffectHost, InlineEffectHost, Residency,
225        RuntimeEnvironment, RuntimeHostConfig, TerminationPolicy,
226    };
227}
228
229pub mod runtime {
230    pub use crate::core::AdvancedLashCoreBuilder;
231    pub use lash_core::runtime::{
232        AssembledTurn, DirectCompletionClient, EffectScope, EmbeddedRuntimeHost, EventSink,
233        InlineRuntimeEffectController, LashRuntime, LlmAttachmentSpec, LlmRequestSpec,
234        NoopEventSink, NoopTurnActivitySink, ProcessCommand, ProcessEffectOutcome, QueuedWorkPoke,
235        QueuedWorkRunHandle, QueuedWorkRunOutcome, QueuedWorkRunRequest, QueuedWorkRunner,
236        RuntimeEffectCommand, RuntimeEffectController, RuntimeEffectControllerError,
237        RuntimeEffectEnvelope, RuntimeEffectKind, RuntimeEffectLocalExecutor, RuntimeEffectOutcome,
238        RuntimeEnvironmentBuilder, RuntimeError, RuntimeErrorCode, RuntimeHandle,
239        RuntimeInvocation, RuntimeObservation, RuntimeScope, RuntimeTurnPhase,
240        RuntimeTurnPhaseProbe, ScopedEffectController, TurnContext,
241    };
242    pub use lash_core::{
243        PersistentRuntimeServices, PluginMessage, ProtocolSessionExtensionHandle,
244        ProtocolTurnOptions, SessionEvent, SessionHandle, SessionPolicy, SessionSnapshot,
245        TurnCause, TurnFinish, TurnOutcome, TurnStop, render_turn_causes_prompt,
246    };
247}
248
249pub mod prompt {
250    pub use lash_core::{
251        PromptBuiltin, PromptContribution, PromptContributionGate, PromptLayer, PromptSlot,
252        PromptTemplate, PromptTemplateEntry, PromptTemplateSection, default_prompt_template,
253    };
254}
255
256pub mod tracing {
257    pub use lash_core::{
258        JsonlTraceSink, TraceAttachment, TraceBranchSelection, TraceContentBlock, TraceError,
259        TraceEvent, TraceLabelMetadata, TraceLashlangChildExecution, TraceLashlangEdgeSelection,
260        TraceLashlangExecutionEvent, TraceLashlangExecutionIdentity, TraceLashlangGraph,
261        TraceLashlangGraphChildLink, TraceLashlangGraphEdge, TraceLashlangGraphNode,
262        TraceLashlangGraphStore, TraceLashlangMap, TraceLashlangMapEdge, TraceLashlangMapNode,
263        TraceLashlangNodeStatus, TraceLashlangStatus, TraceLlmMessage, TraceLlmRequest,
264        TraceLlmResponse, TracePromptComponent, TraceProviderStreamEvent, TraceRecord,
265        TraceRuntimeScope, TraceRuntimeStreamEvent, TraceRuntimeSubject, TraceSinkError,
266        TraceTokenUsage, TraceToolSpec,
267    };
268    pub use lash_trace::{StderrTraceSink, TeeTraceSink, TraceContext, TraceLevel, TraceSink};
269}
270
271/// Test helpers for embedders. Enable with `lash = { ..., features = ["testing"] }`
272/// to script model responses in integration tests without a live provider.
273#[cfg(any(test, feature = "testing"))]
274pub mod testing;
275
276pub mod provider {
277    pub use lash_core::provider::{
278        ProviderRateLimitPolicy, ProviderReliability, ProviderRetryPolicy,
279    };
280    pub use lash_core::{
281        LlmTimeouts, Provider, ProviderComponents, ProviderFactory, ProviderHandle,
282        ProviderModelPolicy, ProviderOptions, ProviderSpec, RequestTimeout, StaticModelPolicy,
283    };
284}
lash/lib.rs

lash/
lib.rs
