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

lash/
lib.rs
