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

lash/
lib.rs
