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`], [`triggers`], ...) carries its own
11//! vocabulary. [`prelude`] mirrors the crate root exactly.
12
13pub mod admin;
14mod core;
15mod error;
16mod plugin_binding;
17mod prompt_layer;
18#[cfg(feature = "rlm")]
19pub mod rlm;
20pub mod scenario_contracts;
21mod session;
22mod support;
23#[cfg(all(test, feature = "rlm"))]
24mod tests;
25pub mod turn;
26pub mod usage;
27
28pub use crate::admin::{
29    AdvancedToolAdmin, Completions, CoreTriggerAdmin, PluginOperations, SessionCommandAdmin,
30    SessionTriggerAdmin, ToolAdmin,
31};
32pub use crate::core::{
33    LashCore, LashCoreBuilder, SessionDeleteReport, StandardCore, StandardCoreBuilder,
34};
35#[cfg(feature = "rlm")]
36pub use crate::core::{RlmCore, RlmCoreBuilder};
37pub use crate::error::{EmbedError, Result};
38pub use crate::plugin_binding::PluginBinding;
39pub use crate::prompt_layer::PromptLayerSink;
40pub use crate::session::{
41    EnqueueTurnBuilder, LashSession, ObservableSession, SessionBuilder, SessionConfigPatch,
42};
43pub use crate::turn::{
44    QueuedTurnBuilder, TurnActivityFanout, TurnBuilder, TurnOutput, TurnResult, TurnStream,
45    message_role, message_text,
46};
47pub use lash_core::{
48    AwaitEventKey, AwaitEventWaitIdentity, ExternalCompletionError, InputItem, ModelLimits,
49    ModelSpec, PendingTurnInput, PendingTurnInputCancelOutcome, PendingTurnInputCancelResult,
50    PendingTurnInputCancelTarget, PendingTurnInputSuffixCancelOutcome, PluginStack, Resolution,
51    ResolveOutcome, SessionCommand, SessionCommandReceipt, SessionSpec, TurnActivity,
52    TurnActivityId, TurnActivitySink, TurnEvent, TurnInput,
53};
54/// Cooperative cancellation handle accepted by
55/// [`TurnBuilder::cancel`](crate::TurnBuilder::cancel); re-exported so
56/// embedders cancel turns without depending on `tokio-util` themselves.
57pub use tokio_util::sync::CancellationToken;
58
59/// The prelude is exactly the crate root: `use lash::prelude::*;` brings in
60/// the daily core/session/turn vocabulary and nothing from the domain
61/// modules.
62pub mod prelude {
63    pub use crate::{
64        AdvancedToolAdmin, CoreTriggerAdmin, EmbedError, EnqueueTurnBuilder, InputItem, LashCore,
65        LashCoreBuilder, LashSession, ModelLimits, ModelSpec, ObservableSession,
66        PendingTurnInputCancelOutcome, PluginBinding, PluginOperations, PluginStack,
67        PromptLayerSink, QueuedTurnBuilder, Result, SessionBuilder, SessionCommand,
68        SessionCommandAdmin, SessionCommandReceipt, SessionConfigPatch, SessionDeleteReport,
69        SessionSpec, SessionTriggerAdmin, StandardCore, StandardCoreBuilder, ToolAdmin,
70        TurnActivity, TurnActivityFanout, TurnActivityId, TurnActivitySink, TurnBuilder, TurnEvent,
71        TurnInput, TurnOutput, TurnResult, TurnStream, message_role, message_text,
72    };
73    #[cfg(feature = "rlm")]
74    pub use crate::{RlmCore, RlmCoreBuilder};
75}
76
77/// Session observation: cursors, resumable event streams, and live replay
78/// recovery for host frontends. Entry point: [`LashSession::observe`] /
79/// [`ObservableSession`].
80pub mod observe {
81    pub use crate::session::{
82        RemoteSessionObservationEventStream, RemoteSessionObservationStream,
83        RemoteSessionObservationStreamItem, RemoteSessionObservationSubscription,
84        SessionObservationStream, SessionObservationStreamItem,
85    };
86    pub use lash_core::{
87        LiveReplayGap, LiveReplayGapReason, SessionCursor, SessionObservation,
88        SessionObservationEvent, SessionObservationEventPayload, SessionObservationSubscription,
89        SessionProcessEventKind, SessionQueueEventKind, SessionResume, SessionRevision,
90    };
91}
92
93/// Triggers and subscriptions: declaring event sources, emitting occurrences,
94/// and inspecting trigger subscriptions. Entry points:
95/// [`LashCore::triggers`] and [`LashSession::triggers`].
96pub mod triggers {
97    pub use lash_core::{
98        LashSchema, TriggerEmitReport, TriggerEvent, TriggerEventType, TriggerOccurrenceRequest,
99        TriggerRegistration, TriggerSubscriptionDraft, TriggerSubscriptionFilter,
100        TriggerTargetSummary, empty_trigger_source_key,
101    };
102}
103
104pub mod tools {
105    pub use lash_core::{
106        CancelHint, PendingCompletion, PreparedToolCall, TimeoutBehavior, ToolActivation,
107        ToolArgumentProjectionPolicy, ToolCall, ToolCallOutput, ToolCallRecord, ToolContext,
108        ToolContract, ToolDefinition, ToolDurableEffects, ToolExecutionGrant, ToolManifest,
109        ToolOutputContract, ToolPrepareCall, ToolPrepareContext, ToolProvider, ToolResult,
110        ToolScheduling, ToolSourceHandle, ToolTriggerClient,
111    };
112    pub use lash_core::{PLUGIN_TOOL_SOURCE_ID, ToolRestoreReport, ToolState, ToolStateEntry};
113    #[cfg(feature = "rlm")]
114    pub use lash_lashlang_runtime::{
115        CataloguePreviewEntry, CataloguePreviewOptions, DEFAULT_CATALOGUE_PREVIEW_CALL_NAME_LIMIT,
116        DEFAULT_CATALOGUE_PREVIEW_MODULE_LIMIT, LASHLANG_TOOL_BINDING_KEY, LashlangToolBinding,
117        RemoteToolGrantLashlangExt, ToolDefinitionLashlangExt, ToolManifestLashlangExt,
118        catalogue_preview_contribution, catalogue_preview_contribution_for_entries,
119        catalogue_preview_contribution_for_entries_with_options,
120        catalogue_preview_contribution_for_manifests, catalogue_preview_contribution_with_options,
121        catalogue_preview_entries_from_catalog_records, catalogue_preview_entries_from_manifests,
122        catalogue_preview_entry_from_catalog_record, catalogue_preview_entry_from_manifest,
123    };
124    #[cfg(feature = "rlm")]
125    pub use lash_lashlang_runtime::{
126        DeferredResolutionRecord, DeferredToolResolver, Resolution as DeferredToolResolution,
127        SharedDeferredToolResolver, ToolGrant as DeferredToolGrant,
128    };
129    /// Author a fixed-tool provider without hand-rolling `tool_manifests` /
130    /// `resolve_contract`: supply the [`ToolDefinition`]s once and an
131    /// [`StaticToolExecute`] for behavior.
132    pub use lash_tool_support::{StaticToolExecute, StaticToolProvider};
133}
134
135pub mod direct {
136    pub use lash_core::llm::types::{
137        LlmAttachment, LlmEventSender, LlmOutputPart, LlmTerminalReason, LlmUsage,
138    };
139    pub use lash_core::{
140        DirectCompletion, DirectJsonSchema, DirectLlmClient, DirectLlmCompletion, DirectLlmError,
141        DirectMessage, DirectOutputSpec, DirectPart, DirectRequest, DirectRole, LlmResponse,
142        TokenUsage,
143    };
144}
145
146pub mod persistence {
147    pub use lash_core::FileAttachmentStore;
148    pub use lash_core::runtime::{
149        DeliveryPolicy, InMemorySessionStore, InMemorySessionStoreFactory, MergeKey,
150        PendingTurnInput, PendingTurnInputCancelOutcome, PendingTurnInputCancelResult,
151        PendingTurnInputCancelTarget, PendingTurnInputClaimDiagnostics, PendingTurnInputDraft,
152        PendingTurnInputSuffixCancelOutcome, QueuedWorkBatch, QueuedWorkBatchDraft,
153        QueuedWorkClaim, QueuedWorkClaimBoundary, QueuedWorkClass, QueuedWorkCompletion,
154        QueuedWorkItem, QueuedWorkPayload, RuntimeSessionState, SessionStoreCreateRequest,
155        SessionStoreFactory, SlotPolicy,
156    };
157    pub use lash_core::store::queued_work;
158    pub use lash_core::store::{
159        GraphCommitDelta, HydratedSessionCheckpoint, PersistedSessionRead, RuntimeCommit,
160        RuntimeCommitResult, RuntimeTurnCommitStamp, SessionCheckpoint, SessionHead,
161        SessionHeadMeta, load_persisted_session_state, load_persisted_session_state_active_path,
162    };
163    pub use lash_core::{
164        AttachmentStore, InMemoryAttachmentStore, InMemoryProcessExecutionEnvStore,
165        ProcessExecutionEnvStore,
166    };
167    pub use lash_core::{
168        BlobRef, GcReport, LeaseOwnerIdentity, LeaseOwnerLiveness, PersistedSessionConfig,
169        PersistedTurnState, ProtocolEvent, RuntimePersistence, SessionEventRecord,
170        SessionExecutionLease, SessionExecutionLeaseClaimOutcome, SessionExecutionLeaseCompletion,
171        SessionExecutionLeaseFence, SessionGraph, SessionMeta, SessionNodeRecord, SessionReadScope,
172        SessionReadView, SessionRelation, StoreError, TokenLedgerEntry, VacuumReport,
173    };
174    #[cfg(feature = "rlm")]
175    pub use lash_lashlang_runtime::{InMemoryLashlangArtifactStore, LashlangArtifactStore};
176}
177
178pub mod plugins {
179    pub use crate::plugin_binding::PluginBinding;
180    pub use lash_core::PluginDirective;
181    pub use lash_core::plugin::{
182        AfterToolCallHook, AfterTurnHook, AssistantResponseHook, AssistantResponseHookContext,
183        AssistantResponseTransform, AssistantStreamHook, AssistantStreamHookContext,
184        AssistantStreamTransform, BeforeToolCallHook, BeforeTurnHook, CheckpointHook,
185        CheckpointHookContext, CompactionContext, ContextCompaction, ContextCompactor,
186        ContextError, PluginExtensionContribution, PluginSpecBuilder, StaticPluginFactory,
187        ToolCallHookContext, ToolResultHookContext,
188    };
189    pub use lash_core::{
190        PluginError, PluginFactory, PluginHost, PluginMessage, PluginRegistrar, PluginRuntimeEvent,
191        PluginSession, PluginSessionContext, PluginSpec, PluginSpecFactory, PromptHookContext,
192        SessionPlugin, ToolCatalogContribution, TurnHookContext, TurnResultHookContext,
193    };
194    pub use lash_plugin_tool_output_budget::{
195        ToolOutputBudgetConfig, ToolOutputBudgetMode, ToolOutputBudgetPluginFactory,
196        tool_output_budget_stack as runtime_plugin_stack,
197    };
198}
199
200pub mod messages {
201    pub use lash_core::MessageRole;
202}
203
204pub mod remote {
205    pub use lash_remote_protocol::{
206        REMOTE_PROTOCOL_VERSION, RemoteAssistantOutput, RemoteAssistantOutputState,
207        RemoteAttachmentRef, RemoteCausalRef, RemoteDiagnostic, RemoteExecutionSummary,
208        RemoteGenerationOptions, RemoteInputItem, RemoteLiveReplayGap, RemoteLiveReplayGapReason,
209        RemoteLlmAttachment, RemoteLlmContentBlock, RemoteLlmMessage, RemoteLlmOutputPart,
210        RemoteLlmOutputSpec, RemoteLlmRequest, RemoteLlmRequestScope, RemoteLlmResponse,
211        RemoteLlmRole, RemoteLlmTerminalReason, RemoteLlmToolChoice, RemoteLlmToolSpec,
212        RemoteModelIntent, RemoteObservedProcess, RemoteObservedProcessEvent,
213        RemotePersistProcessEnvRequest, RemotePersistProcessEnvResult, RemoteProcessAwaitOutput,
214        RemoteProcessAwaitRequest, RemoteProcessAwaitResult, RemoteProcessCancelRequest,
215        RemoteProcessCancelResult, RemoteProcessDefinitionIdentity, RemoteProcessEvent,
216        RemoteProcessEventSemantics, RemoteProcessEventSemanticsSpec, RemoteProcessEventType,
217        RemoteProcessEventsRequest, RemoteProcessEventsResponse, RemoteProcessExecutionEnvRef,
218        RemoteProcessExecutionEnvSpec, RemoteProcessExecutionPolicy, RemoteProcessExternalRef,
219        RemoteProcessHandleDescriptor, RemoteProcessInput, RemoteProcessLifecycleStatus,
220        RemoteProcessListFilter, RemoteProcessListResponse, RemoteProcessModelLimits,
221        RemoteProcessModelSpec, RemoteProcessOriginator, RemoteProcessPluginOptions,
222        RemoteProcessProvenance, RemoteProcessSignalRequest, RemoteProcessSignalResult,
223        RemoteProcessStartGrant, RemoteProcessStartRequest, RemoteProcessStartResult,
224        RemoteProcessStatus, RemoteProcessStatusFilter, RemoteProcessSummary,
225        RemoteProcessTerminalSemantics, RemoteProcessTerminalSpec, RemoteProcessTerminalState,
226        RemoteProcessValueSelector, RemoteProcessWaitKind, RemoteProcessWaitState,
227        RemoteProcessWake, RemoteProcessWakeDedupeKey, RemoteProcessWakeSpec,
228        RemoteProcessWorkItem, RemoteProcessWorkSnapshot, RemotePromptBuiltin,
229        RemotePromptContribution, RemotePromptContributionGate, RemotePromptLayer,
230        RemotePromptSlot, RemotePromptSlotLayer, RemotePromptTemplate, RemotePromptTemplateEntry,
231        RemotePromptTemplateSection, RemoteProtocolError, RemoteProtocolTurnOptions,
232        RemoteProviderMetadata, RemoteProviderReasoningReplay, RemoteProviderReplayMeta,
233        RemoteResponseTextMeta, RemoteRuntimeEffectKind, RemoteRuntimeInvocation,
234        RemoteRuntimeReplay, RemoteRuntimeScope, RemoteRuntimeSubject,
235        RemoteSchemaProjectionOverride, RemoteSessionCursor, RemoteSessionObservation,
236        RemoteSessionObservationEvent, RemoteSessionObservationEventPayload,
237        RemoteSessionProcessEventKind, RemoteSessionQueueEventKind, RemoteSessionScope,
238        RemoteTokenLedgerEntry, RemoteToolActivation, RemoteToolArgumentProjectionPolicy,
239        RemoteToolCallOutcome, RemoteToolCallSummary, RemoteToolFailureClass, RemoteToolGrant,
240        RemoteToolOutputContract, RemoteToolRegistry, RemoteToolRetryPolicy, RemoteToolScheduling,
241        RemoteTriggerCancelSubscriptionRequest, RemoteTriggerCancelSubscriptionResult,
242        RemoteTriggerEmitReport, RemoteTriggerInputBinding, RemoteTriggerInputTemplate,
243        RemoteTriggerListSubscriptionsResponse, RemoteTriggerOccurrenceRecord,
244        RemoteTriggerOccurrenceRequest, RemoteTriggerRegisterSubscriptionRequest,
245        RemoteTriggerRegisterSubscriptionResult, RemoteTriggerRegistration,
246        RemoteTriggerSubscriptionDraft, RemoteTriggerSubscriptionFilter,
247        RemoteTriggerSubscriptionRecord, RemoteTriggerTargetSummary, RemoteTurnActivity,
248        RemoteTurnEvent, RemoteTurnFinish, RemoteTurnInput, RemoteTurnIssue, RemoteTurnOutcome,
249        RemoteTurnRequest, RemoteTurnResult, RemoteTurnStatus, RemoteTurnStop,
250        RemoteTurnUsageSummary, RemoteUsage, assert_remote_tool_registry_reopenable,
251        ensure_protocol_version,
252    };
253}
254
255pub mod process {
256    pub use crate::admin::{Processes, SessionProcessAdmin};
257    pub use lash_core::{
258        ObservedProcess, ObservedProcessEvent, ObservedWorkItem, ProcessAwaitOutput,
259        ProcessCancelAbility, ProcessCancelAllRequest, ProcessCancelRequest, ProcessCancelSource,
260        ProcessCancelSummary, ProcessEvent, ProcessEventAppendRequest, ProcessEventAppendResult,
261        ProcessEventType, ProcessExecutionContext, ProcessExecutionEnvRef, ProcessExecutionEnvSpec,
262        ProcessExternalRef, ProcessHandleDescriptor, ProcessHandleGrant, ProcessHandleSummary,
263        ProcessIdentity, ProcessInput, ProcessLease, ProcessLeaseCompletion,
264        ProcessLifecycleStatus, ProcessListFilter, ProcessListMode, ProcessOpScope, ProcessRecord,
265        ProcessRegistration, ProcessRegistry, ProcessRunHandle, ProcessRuntimeHost, ProcessService,
266        ProcessSessionDeleteReport, ProcessStartOptions, ProcessStartRequest, ProcessStatus,
267        ProcessStatusFilter, ProcessTerminalState, ProcessWake, ProcessWakeDedupeKey,
268        ProcessWakeDelivery, ProcessWakeSpec, ProcessWorkDriver, ProcessWorkObserver,
269        ProcessWorkSnapshot, SessionScope, SessionScopeId,
270    };
271    #[cfg(feature = "rlm")]
272    pub use lash_lashlang_runtime::{
273        LASHLANG_ENGINE_KIND, LASHLANG_TOOL_BINDING_KEY, LashlangProcessInput,
274        lashlang_process_event_types, lashlang_process_signal_event_types,
275    };
276}
277
278pub mod durability {
279    pub use lash_core::{
280        DurableProcessWorker, DurableProcessWorkerConfig, EffectHost, InlineEffectHost, Residency,
281        RuntimeEnvironment, RuntimeHostConfig, TerminationPolicy,
282    };
283}
284
285pub mod runtime {
286    pub use crate::core::AdvancedLashCoreBuilder;
287    pub use lash_core::runtime::{
288        AssembledTurn, DirectCompletionClient, EmbeddedRuntimeHost, EventSink, ExecutionScope,
289        InlineRuntimeEffectController, LashRuntime, LlmAttachmentSpec, LlmRequestSpec,
290        NoopEventSink, NoopTurnActivitySink, ProcessCommand, ProcessEffectOutcome,
291        QueuedWorkDriver, QueuedWorkRunHandle, QueuedWorkRunRequest, RuntimeEffectCommand,
292        RuntimeEffectController, RuntimeEffectControllerError, RuntimeEffectEnvelope,
293        RuntimeEffectKind, RuntimeEffectLocalExecutor, RuntimeEffectOutcome,
294        RuntimeEnvironmentBuilder, RuntimeError, RuntimeErrorCode, RuntimeHandle,
295        RuntimeInvocation, RuntimeObservation, RuntimeScope, RuntimeTurnPhase,
296        RuntimeTurnPhaseProbe, ScopedEffectController, TurnContext,
297    };
298    pub use lash_core::{
299        PersistentRuntimeServices, PluginMessage, ProtocolSessionExtensionHandle,
300        ProtocolTurnOptions, SessionHandle, SessionPolicy, SessionSnapshot, TurnCause, TurnFinish,
301        TurnOutcome, TurnStop, render_turn_causes_prompt,
302    };
303}
304
305pub mod prompt {
306    pub use lash_core::{
307        PromptBuiltin, PromptContribution, PromptContributionGate, PromptLayer, PromptSlot,
308        PromptTemplate, PromptTemplateEntry, PromptTemplateSection, default_prompt_template,
309    };
310}
311
312pub mod tracing {
313    pub use lash_core::{
314        JsonlTraceSink, TraceAttachment, TraceBranchSelection, TraceContentBlock, TraceError,
315        TraceEvent, TraceLabelMetadata, TraceLlmMessage, TraceLlmRequest, TraceLlmResponse,
316        TracePromptComponent, TraceProviderStreamEvent, TraceRecord, TraceRuntimeScope,
317        TraceRuntimeStreamEvent, TraceRuntimeSubject, TraceSinkError, TraceTokenUsage,
318        TraceToolSpec,
319    };
320    #[cfg(feature = "rlm")]
321    pub use lash_lashlang_runtime::{
322        TraceLashlangChildExecution, TraceLashlangEdgeSelection, TraceLashlangExecutionEvent,
323        TraceLashlangExecutionIdentity, TraceLashlangGraph, TraceLashlangGraphChildLink,
324        TraceLashlangGraphEdge, TraceLashlangGraphNode, TraceLashlangGraphStore, TraceLashlangMap,
325        TraceLashlangMapEdge, TraceLashlangMapNode, TraceLashlangNodeStatus, TraceLashlangStatus,
326    };
327    pub use lash_trace::{StderrTraceSink, TeeTraceSink, TraceContext, TraceLevel, TraceSink};
328}
329
330/// Test helpers for embedders. Enable with `lash = { ..., features = ["testing"] }`
331/// to script model responses in integration tests without a live provider.
332#[cfg(all(any(test, feature = "testing"), feature = "rlm"))]
333pub mod testing;
334
335pub mod provider {
336    pub use lash_core::provider::{
337        ProviderRateLimitPolicy, ProviderReliability, ProviderRetryPolicy,
338    };
339    pub use lash_core::{
340        LlmTimeouts, Provider, ProviderComponents, ProviderFactory, ProviderHandle,
341        ProviderModelPolicy, ProviderOptions, ProviderSpec, RequestTimeout, StaticModelPolicy,
342    };
343}
lash/lib.rs

lash/
lib.rs
