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

lash/
lib.rs
