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

lash/
lib.rs
