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

lash/
lib.rs
