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

lash/
lib.rs
