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

lash/
lib.rs
