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, PluginActions, 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, PluginActions,
63        PluginBinding, 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, SessionGraph, SessionMeta, SessionNodeRecord,
147        SessionReadScope, SessionReadView, SessionRelation, StoreError, TokenLedgerEntry,
148        VacuumReport,
149    };
150    #[cfg(feature = "rlm")]
151    pub use lash_lashlang_runtime::{InMemoryLashlangArtifactStore, LashlangArtifactStore};
152}
153
154pub mod plugins {
155    pub use crate::plugin_binding::PluginBinding;
156    pub use lash_core::PluginDirective;
157    pub use lash_core::plugin::{
158        AfterToolCallHook, AfterTurnHook, AssistantResponseHook, AssistantResponseHookContext,
159        AssistantResponseTransform, AssistantStreamHook, AssistantStreamHookContext,
160        AssistantStreamTransform, BeforeToolCallHook, BeforeTurnHook, CheckpointHook,
161        CheckpointHookContext, CompactionContext, ContextCompaction, ContextCompactor,
162        ContextError, PluginExtensionContribution, PluginSpecBuilder, StaticPluginFactory,
163        ToolCallHookContext, ToolResultHookContext,
164    };
165    pub use lash_core::{
166        PluginError, PluginFactory, PluginHost, PluginMessage, PluginRegistrar, PluginRuntimeEvent,
167        PluginSession, PluginSessionContext, PluginSpec, PluginSpecFactory, PromptHookContext,
168        SessionPlugin, ToolCatalogContribution, ToolCatalogOverride, TurnHookContext,
169        TurnResultHookContext,
170    };
171    pub use lash_plugin_tool_output_budget::{
172        ToolOutputBudgetConfig, ToolOutputBudgetMode, ToolOutputBudgetPluginFactory,
173        tool_output_budget_stack as runtime_plugin_stack,
174    };
175}
176
177pub mod messages {
178    pub use lash_core::MessageRole;
179}
180
181pub mod remote {
182    pub use lash_remote_protocol::{
183        REMOTE_PROTOCOL_VERSION, RemoteAssistantOutput, RemoteAssistantOutputState,
184        RemoteAttachmentRef, RemoteCausalRef, RemoteDiagnostic, RemoteExecutionSummary,
185        RemoteGenerationOptions, RemoteInputItem, RemoteLiveReplayGap, RemoteLiveReplayGapReason,
186        RemoteLlmAttachment, RemoteLlmContentBlock, RemoteLlmMessage, RemoteLlmOutputPart,
187        RemoteLlmOutputSpec, RemoteLlmRequest, RemoteLlmRequestMetadata, RemoteLlmResponse,
188        RemoteLlmRole, RemoteLlmTerminalReason, RemoteLlmToolChoice, RemoteLlmToolSpec,
189        RemoteModelIntent, RemoteObservedProcess, RemoteObservedProcessEvent,
190        RemotePersistProcessEnvRequest, RemotePersistProcessEnvResult, RemoteProcessAwaitOutput,
191        RemoteProcessAwaitRequest, RemoteProcessAwaitResult, RemoteProcessCancelRequest,
192        RemoteProcessCancelResult, RemoteProcessDefinitionIdentity, RemoteProcessEvent,
193        RemoteProcessEventSemantics, RemoteProcessEventSemanticsSpec, RemoteProcessEventType,
194        RemoteProcessEventsRequest, RemoteProcessEventsResponse, RemoteProcessExecutionEnvRef,
195        RemoteProcessExecutionEnvSpec, RemoteProcessExecutionPolicy, RemoteProcessExternalRef,
196        RemoteProcessHandleDescriptor, RemoteProcessInput, RemoteProcessLifecycleStatus,
197        RemoteProcessListFilter, RemoteProcessListResponse, RemoteProcessModelLimits,
198        RemoteProcessModelSpec, RemoteProcessOriginator, RemoteProcessPluginOptions,
199        RemoteProcessProvenance, RemoteProcessSignalRequest, RemoteProcessSignalResult,
200        RemoteProcessStartGrant, RemoteProcessStartRequest, RemoteProcessStartResult,
201        RemoteProcessStatus, RemoteProcessStatusFilter, RemoteProcessSummary,
202        RemoteProcessTerminalSemantics, RemoteProcessTerminalSpec, RemoteProcessTerminalState,
203        RemoteProcessValueSelector, RemoteProcessWaitKind, RemoteProcessWaitState,
204        RemoteProcessWake, RemoteProcessWakeDedupeKey, RemoteProcessWakeSpec,
205        RemoteProcessWorkItem, RemoteProcessWorkSnapshot, RemotePromptBuiltin,
206        RemotePromptContribution, RemotePromptContributionGate, RemotePromptLayer,
207        RemotePromptSlot, RemotePromptSlotLayer, RemotePromptTemplate, RemotePromptTemplateEntry,
208        RemotePromptTemplateSection, RemoteProtocolError, RemoteProtocolTurnOptions,
209        RemoteProviderMetadata, RemoteProviderReasoningReplay, RemoteProviderReplayMeta,
210        RemoteResponseTextMeta, RemoteRuntimeEffectKind, RemoteRuntimeInvocation,
211        RemoteRuntimeReplay, RemoteRuntimeScope, RemoteRuntimeSubject,
212        RemoteSchemaProjectionOverride, RemoteSessionCursor, RemoteSessionObservationEvent,
213        RemoteSessionObservationEventPayload, RemoteSessionProcessEventKind,
214        RemoteSessionQueueEventKind, RemoteSessionScope, RemoteTokenLedgerEntry,
215        RemoteToolActivation, RemoteToolArgumentProjectionPolicy, RemoteToolAvailability,
216        RemoteToolCallOutcome, RemoteToolCallSummary, RemoteToolFailureClass, RemoteToolGrant,
217        RemoteToolOutputContract, RemoteToolRegistry, RemoteToolRetryPolicy, RemoteToolScheduling,
218        RemoteTriggerCancelSubscriptionRequest, RemoteTriggerCancelSubscriptionResult,
219        RemoteTriggerEmitReport, RemoteTriggerInputBinding, RemoteTriggerInputTemplate,
220        RemoteTriggerListSubscriptionsResponse, RemoteTriggerOccurrenceRecord,
221        RemoteTriggerOccurrenceRequest, RemoteTriggerRegisterSubscriptionRequest,
222        RemoteTriggerRegisterSubscriptionResult, RemoteTriggerRegistration,
223        RemoteTriggerSubscriptionDraft, RemoteTriggerSubscriptionFilter,
224        RemoteTriggerSubscriptionRecord, RemoteTriggerTargetSummary, RemoteTurnActivity,
225        RemoteTurnEvent, RemoteTurnFinish, RemoteTurnInput, RemoteTurnIssue, RemoteTurnOutcome,
226        RemoteTurnRequest, RemoteTurnResult, RemoteTurnStatus, RemoteTurnStop,
227        RemoteTurnUsageSummary, RemoteUsage, assert_remote_tool_registry_reopenable,
228        ensure_protocol_version,
229    };
230}
231
232pub mod process {
233    pub use crate::admin::{Processes, SessionProcessAdmin};
234    pub use lash_core::{
235        ObservedProcess, ObservedProcessEvent, ObservedWorkItem, ProcessAwaitOutput,
236        ProcessCancelAbility, ProcessCancelAllRequest, ProcessCancelRequest, ProcessCancelSource,
237        ProcessCancelSummary, ProcessEvent, ProcessEventAppendRequest, ProcessEventAppendResult,
238        ProcessEventType, ProcessExecutionContext, ProcessExecutionEnvRef, ProcessExecutionEnvSpec,
239        ProcessExternalRef, ProcessHandleDescriptor, ProcessHandleGrant, ProcessHandleSummary,
240        ProcessIdentity, ProcessInput, ProcessLease, ProcessLeaseCompletion,
241        ProcessLifecycleStatus, ProcessListFilter, ProcessListMode, ProcessOpScope, ProcessRecord,
242        ProcessRegistration, ProcessRegistry, ProcessRunHandle, ProcessRuntimeHost, ProcessService,
243        ProcessSessionDeleteReport, ProcessStartOptions, ProcessStartRequest, ProcessStatus,
244        ProcessStatusFilter, ProcessTerminalState, ProcessWake, ProcessWakeDedupeKey,
245        ProcessWakeDelivery, ProcessWakeSpec, ProcessWorkDriver, ProcessWorkObserver,
246        ProcessWorkPoke, ProcessWorkRunner, ProcessWorkSnapshot, SessionScope, SessionScopeId,
247    };
248    #[cfg(feature = "rlm")]
249    pub use lash_lashlang_runtime::{
250        LASHLANG_ENGINE_KIND, LASHLANG_TOOL_BINDING_KEY, LashlangProcessInput,
251        lashlang_process_event_types, lashlang_process_signal_event_types,
252    };
253}
254
255pub mod durability {
256    pub use lash_core::{
257        DurableProcessWorker, DurableProcessWorkerConfig, EffectHost, InlineEffectHost, Residency,
258        RuntimeEnvironment, RuntimeHostConfig, TerminationPolicy,
259    };
260}
261
262pub mod runtime {
263    pub use crate::core::AdvancedLashCoreBuilder;
264    pub use lash_core::runtime::{
265        AssembledTurn, DirectCompletionClient, EmbeddedRuntimeHost, EventSink, ExecutionScope,
266        InlineRuntimeEffectController, LashRuntime, LlmAttachmentSpec, LlmRequestSpec,
267        NoopEventSink, NoopTurnActivitySink, ProcessCommand, ProcessEffectOutcome, QueuedWorkPoke,
268        QueuedWorkRunHandle, QueuedWorkRunOutcome, QueuedWorkRunRequest, QueuedWorkRunner,
269        RuntimeEffectCommand, RuntimeEffectController, RuntimeEffectControllerError,
270        RuntimeEffectEnvelope, RuntimeEffectKind, RuntimeEffectLocalExecutor, RuntimeEffectOutcome,
271        RuntimeEnvironmentBuilder, RuntimeError, RuntimeErrorCode, RuntimeHandle,
272        RuntimeInvocation, RuntimeObservation, RuntimeScope, RuntimeTurnPhase,
273        RuntimeTurnPhaseProbe, ScopedEffectController, TurnContext,
274    };
275    pub use lash_core::{
276        PersistentRuntimeServices, PluginMessage, ProtocolSessionExtensionHandle,
277        ProtocolTurnOptions, SessionHandle, SessionPolicy, SessionSnapshot, TurnCause, TurnFinish,
278        TurnOutcome, TurnStop, render_turn_causes_prompt,
279    };
280}
281
282pub mod prompt {
283    pub use lash_core::{
284        PromptBuiltin, PromptContribution, PromptContributionGate, PromptLayer, PromptSlot,
285        PromptTemplate, PromptTemplateEntry, PromptTemplateSection, default_prompt_template,
286    };
287}
288
289pub mod tracing {
290    pub use lash_core::{
291        JsonlTraceSink, TraceAttachment, TraceBranchSelection, TraceContentBlock, TraceError,
292        TraceEvent, TraceLabelMetadata, TraceLlmMessage, TraceLlmRequest, TraceLlmResponse,
293        TracePromptComponent, TraceProviderStreamEvent, TraceRecord, TraceRuntimeScope,
294        TraceRuntimeStreamEvent, TraceRuntimeSubject, TraceSinkError, TraceTokenUsage,
295        TraceToolSpec,
296    };
297    #[cfg(feature = "rlm")]
298    pub use lash_lashlang_runtime::{
299        TraceLashlangChildExecution, TraceLashlangEdgeSelection, TraceLashlangExecutionEvent,
300        TraceLashlangExecutionIdentity, TraceLashlangGraph, TraceLashlangGraphChildLink,
301        TraceLashlangGraphEdge, TraceLashlangGraphNode, TraceLashlangGraphStore, TraceLashlangMap,
302        TraceLashlangMapEdge, TraceLashlangMapNode, TraceLashlangNodeStatus, TraceLashlangStatus,
303    };
304    pub use lash_trace::{StderrTraceSink, TeeTraceSink, TraceContext, TraceLevel, TraceSink};
305}
306
307/// Test helpers for embedders. Enable with `lash = { ..., features = ["testing"] }`
308/// to script model responses in integration tests without a live provider.
309#[cfg(all(any(test, feature = "testing"), feature = "rlm"))]
310pub mod testing;
311
312pub mod provider {
313    pub use lash_core::provider::{
314        ProviderRateLimitPolicy, ProviderReliability, ProviderRetryPolicy,
315    };
316    pub use lash_core::{
317        LlmTimeouts, Provider, ProviderComponents, ProviderFactory, ProviderHandle,
318        ProviderModelPolicy, ProviderOptions, ProviderSpec, RequestTimeout, StaticModelPolicy,
319    };
320}
lash/lib.rs

lash/
lib.rs
