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 mode;
17mod plugin_binding;
18mod prompt_layer;
19mod session;
20mod support;
21#[cfg(test)]
22mod tests;
23pub mod turn;
24pub mod usage;
25
26pub use crate::admin::{
27    AdvancedToolAdmin, Completions, CoreTriggerAdmin, PluginActions, SessionCommandAdmin,
28    SessionTriggerAdmin, ToolAdmin,
29};
30pub use crate::core::{LashCore, LashCoreBuilder, SessionDeleteReport};
31pub use crate::error::{EmbedError, Result};
32pub use crate::mode::{ModeId, ModePreset};
33pub use crate::plugin_binding::PluginBinding;
34pub use crate::prompt_layer::PromptLayerSink;
35pub use crate::session::{
36    EnqueueTurnBuilder, LashSession, ObservableSession, SessionBuilder, SessionConfigPatch,
37};
38pub use crate::turn::{
39    QueuedTurnBuilder, TurnActivityFanout, TurnBuilder, TurnOutput, TurnResult, TurnStream,
40    message_role, message_text,
41};
42pub use lash_core::{
43    AwaitEventKey, AwaitEventWaitIdentity, ExternalCompletionError, InputItem, ModelLimits,
44    ModelSpec, PluginStack, Resolution, ResolveOutcome, SessionCommand, SessionCommandReceipt,
45    SessionSpec, TurnActivity, TurnActivityId, TurnActivitySink, TurnEvent, TurnInput,
46};
47/// Cooperative cancellation handle accepted by
48/// [`TurnBuilder::cancel`](crate::TurnBuilder::cancel); re-exported so
49/// embedders cancel turns without depending on `tokio-util` themselves.
50pub use tokio_util::sync::CancellationToken;
51
52/// The prelude is exactly the crate root: `use lash::prelude::*;` brings in
53/// the daily core/session/turn vocabulary and nothing from the domain
54/// modules.
55pub mod prelude {
56    pub use crate::{
57        AdvancedToolAdmin, CoreTriggerAdmin, EmbedError, EnqueueTurnBuilder, InputItem, LashCore,
58        LashCoreBuilder, LashSession, ModeId, ModePreset, ModelLimits, ModelSpec,
59        ObservableSession, PluginActions, PluginBinding, PluginStack, PromptLayerSink,
60        QueuedTurnBuilder, Result, SessionBuilder, SessionCommand, SessionCommandAdmin,
61        SessionCommandReceipt, SessionConfigPatch, SessionDeleteReport, SessionSpec,
62        SessionTriggerAdmin, ToolAdmin, TurnActivity, TurnActivityFanout, TurnActivityId,
63        TurnActivitySink, TurnBuilder, TurnEvent, TurnInput, TurnOutput, TurnResult, TurnStream,
64        message_role, message_text,
65    };
66}
67
68/// Session observation: cursors, resumable event streams, and live replay
69/// recovery for host frontends. Entry point: [`LashSession::observe`] /
70/// [`ObservableSession`].
71pub mod observe {
72    pub use lash_core::{
73        SessionCursor, SessionObservation, SessionObservationEvent, SessionObservationEventPayload,
74        SessionObservationSubscription, SessionProcessEventKind, SessionQueueEventKind,
75        SessionResume, SessionRevision,
76    };
77}
78
79/// Triggers and subscriptions: declaring event sources, emitting occurrences,
80/// and inspecting trigger subscriptions. Entry points:
81/// [`LashCore::triggers`] and [`LashSession::triggers`].
82pub mod triggers {
83    pub use lash_core::{
84        TriggerEmitReport, TriggerEvent, TriggerEventType, TriggerOccurrenceRequest,
85        TriggerRegistration, TriggerSubscriptionFilter, TriggerTargetSummary,
86        empty_trigger_source_key,
87    };
88}
89
90pub mod tools {
91    pub use lash_core::{
92        CancelHint, LashlangToolBinding, PendingCompletion, PreparedToolCall, TimeoutBehavior,
93        ToolActivation, ToolArgumentProjectionPolicy, ToolAvailability, ToolAvailabilityConfig,
94        ToolCall, ToolCallOutput, ToolCallRecord, ToolContext, ToolContract, ToolDefinition,
95        ToolDurableEffects, ToolManifest, ToolOutputContract, ToolPrepareCall, ToolPrepareContext,
96        ToolProvider, ToolResult, ToolScheduling, ToolSourceHandle, ToolTriggerClient,
97    };
98    pub use lash_core::{ToolRestoreReport, ToolState, ToolStateEntry};
99    /// Author a fixed-tool provider without hand-rolling `tool_manifests` /
100    /// `resolve_contract`: supply the [`ToolDefinition`]s once and an
101    /// [`StaticToolExecute`] for behavior.
102    pub use lash_tool_support::{StaticToolExecute, StaticToolProvider};
103}
104
105pub mod direct {
106    pub use lash_core::llm::types::{
107        LlmAttachment, LlmEventSender, LlmOutputPart, LlmTerminalReason, LlmUsage,
108    };
109    pub use lash_core::{
110        DirectCompletion, DirectJsonSchema, DirectLlmClient, DirectLlmCompletion, DirectLlmError,
111        DirectMessage, DirectOutputSpec, DirectPart, DirectRequest, DirectRole, LlmResponse,
112        TokenUsage,
113    };
114}
115
116pub mod persistence {
117    pub use lash_core::FileAttachmentStore;
118    pub use lash_core::runtime::{
119        DeliveryPolicy, InMemorySessionStore, InMemorySessionStoreFactory, MergeKey,
120        QueuedWorkBatch, QueuedWorkBatchDraft, QueuedWorkClaim, QueuedWorkClaimBoundary,
121        QueuedWorkCompletion, QueuedWorkItem, QueuedWorkPayload, RuntimeSessionState,
122        SessionStoreCreateRequest, SessionStoreFactory, SlotPolicy,
123    };
124    pub use lash_core::store::queued_work;
125    pub use lash_core::store::{
126        GraphCommitDelta, HydratedSessionCheckpoint, PersistedSessionRead, RuntimeCommit,
127        RuntimeCommitResult, RuntimeTurnCommitStamp, SessionCheckpoint, SessionHead,
128        SessionHeadMeta, load_persisted_session_state, load_persisted_session_state_active_path,
129    };
130    pub use lash_core::{AttachmentStore, InMemoryAttachmentStore};
131    pub use lash_core::{
132        BlobRef, GcReport, PersistedSessionConfig, PersistedTurnState, ProtocolEvent,
133        RuntimePersistence, SessionEventRecord, SessionGraph, SessionMeta, SessionNodeRecord,
134        SessionReadScope, SessionReadView, SessionRelation, StoreError, TokenLedgerEntry,
135        VacuumReport,
136    };
137    pub use lash_core::{InMemoryLashlangArtifactStore, LashlangArtifactStore};
138}
139
140pub mod plugins {
141    pub use crate::plugin_binding::PluginBinding;
142    pub use lash_core::PluginDirective;
143    pub use lash_core::plugin::{
144        AfterToolCallHook, AfterTurnHook, AssistantResponseHook, AssistantResponseHookContext,
145        AssistantResponseTransform, AssistantStreamHook, AssistantStreamHookContext,
146        AssistantStreamTransform, BeforeToolCallHook, BeforeTurnHook, CheckpointHook,
147        CheckpointHookContext, CompactionContext, ContextCompaction, ContextCompactor,
148        ContextError, PluginSpecBuilder, StaticPluginFactory, ToolCallHookContext,
149        ToolResultHookContext,
150    };
151    pub use lash_core::{
152        PluginError, PluginFactory, PluginHost, PluginMessage, PluginRegistrar, PluginRuntimeEvent,
153        PluginSession, PluginSessionContext, PluginSpec, PluginSpecFactory, PromptHookContext,
154        SessionPlugin, ToolCatalogContribution, ToolCatalogOverride, TurnHookContext,
155        TurnResultHookContext,
156    };
157    pub use lash_plugin_tool_output_budget::{
158        ToolOutputBudgetConfig, ToolOutputBudgetMode, ToolOutputBudgetPluginFactory,
159        tool_output_budget_stack as runtime_plugin_stack,
160    };
161}
162
163pub mod modes {
164    pub use crate::mode::{RlmSessionBuilderExt, RlmTurnBuilderExt};
165    pub use lash_protocol_rlm::{
166        LashlangAbilities, LashlangHostCatalog, LashlangHostEnvironment, LashlangLanguageFeatures,
167        NamedDataType, RlmProtocolPluginConfig, TypeExpr, TypeField, format_type_expr,
168    };
169    pub use lash_rlm_types::RlmFinalAnswerFormat;
170}
171
172pub mod messages {
173    pub use lash_core::MessageRole;
174}
175
176pub mod remote {
177    pub use lash_remote_protocol::{
178        REMOTE_PROTOCOL_VERSION, RemoteAssistantOutput, RemoteAssistantOutputState,
179        RemoteAttachmentRef, RemoteCausalRef, RemoteDiagnostic, RemoteExecutionSummary,
180        RemoteGenerationOptions, RemoteInputItem, RemoteLashlangProcessRef,
181        RemoteLashlangToolBinding, RemoteLiveReplayGap, RemoteLiveReplayGapReason,
182        RemoteLlmAttachment, RemoteLlmContentBlock, RemoteLlmMessage, RemoteLlmOutputPart,
183        RemoteLlmOutputSpec, RemoteLlmRequest, RemoteLlmRequestMetadata, RemoteLlmResponse,
184        RemoteLlmRole, RemoteLlmTerminalReason, RemoteLlmToolChoice, RemoteLlmToolSpec,
185        RemoteModelIntent, RemoteObservedProcess, RemoteObservedProcessEvent,
186        RemoteProcessAwaitOutput, RemoteProcessAwaitRequest, RemoteProcessAwaitResult,
187        RemoteProcessCancelRequest, RemoteProcessCancelResult, RemoteProcessDefinitionIdentity,
188        RemoteProcessDefinitionSummary, RemoteProcessEvent, RemoteProcessEventSemantics,
189        RemoteProcessEventSemanticsSpec, RemoteProcessEventType, RemoteProcessEventsRequest,
190        RemoteProcessEventsResponse, RemoteProcessExecutionEnvSpec, RemoteProcessExecutionPolicy,
191        RemoteProcessExternalRef, RemoteProcessHandleDescriptor, RemoteProcessInput,
192        RemoteProcessLifecycleStatus, RemoteProcessListFilter, RemoteProcessListResponse,
193        RemoteProcessModelLimits, RemoteProcessModelSpec, RemoteProcessOriginator,
194        RemoteProcessPluginOptions, RemoteProcessProvenance, RemoteProcessSignalRequest,
195        RemoteProcessSignalResult, RemoteProcessStartGrant, RemoteProcessStartRequest,
196        RemoteProcessStartResult, RemoteProcessStatus, RemoteProcessStatusFilter,
197        RemoteProcessSummary, RemoteProcessTerminalSemantics, RemoteProcessTerminalSpec,
198        RemoteProcessTerminalState, RemoteProcessValueSelector, RemoteProcessWaitKind,
199        RemoteProcessWaitState, RemoteProcessWake, RemoteProcessWakeDedupeKey,
200        RemoteProcessWakeSpec, RemoteProcessWorkItem, RemoteProcessWorkSnapshot,
201        RemotePromptBuiltin, RemotePromptContribution, RemotePromptContributionGate,
202        RemotePromptLayer, RemotePromptSlot, RemotePromptSlotLayer, RemotePromptTemplate,
203        RemotePromptTemplateEntry, RemotePromptTemplateSection, RemoteProtocolError,
204        RemoteProtocolTurnOptions, RemoteProviderMetadata, RemoteProviderReasoningReplay,
205        RemoteProviderReplayMeta, RemoteResponseTextMeta, RemoteRuntimeEffectKind,
206        RemoteRuntimeInvocation, RemoteRuntimeReplay, RemoteRuntimeScope, RemoteRuntimeSubject,
207        RemoteSchemaProjectionOverride, RemoteSessionCursor, RemoteSessionObservationEvent,
208        RemoteSessionObservationEventPayload, RemoteSessionProcessEventKind,
209        RemoteSessionQueueEventKind, RemoteSessionScope, RemoteTokenLedgerEntry,
210        RemoteToolActivation, RemoteToolArgumentProjectionPolicy, RemoteToolAvailability,
211        RemoteToolCallOutcome, RemoteToolCallSummary, RemoteToolFailureClass, RemoteToolGrant,
212        RemoteToolOutputContract, RemoteToolRegistry, RemoteToolRetryPolicy, RemoteToolScheduling,
213        RemoteTriggerCancelSubscriptionRequest, RemoteTriggerCancelSubscriptionResult,
214        RemoteTriggerEmitReport, RemoteTriggerInputBinding, RemoteTriggerInputTemplate,
215        RemoteTriggerListSubscriptionsResponse, RemoteTriggerOccurrenceRecord,
216        RemoteTriggerOccurrenceRequest, RemoteTriggerRegisterSubscriptionRequest,
217        RemoteTriggerRegisterSubscriptionResult, RemoteTriggerRegistration,
218        RemoteTriggerSubscriptionDraft, RemoteTriggerSubscriptionFilter,
219        RemoteTriggerSubscriptionRecord, RemoteTriggerTargetIdentity, RemoteTriggerTargetSummary,
220        RemoteTurnActivity, RemoteTurnEvent, RemoteTurnFinish, RemoteTurnInput, RemoteTurnIssue,
221        RemoteTurnOutcome, RemoteTurnRequest, RemoteTurnResult, RemoteTurnStatus, RemoteTurnStop,
222        RemoteTurnUsageSummary, RemoteUsage, assert_remote_tool_registry_reopenable,
223        ensure_protocol_version,
224    };
225}
226
227pub mod process {
228    pub use crate::admin::{Processes, SessionProcessAdmin};
229    pub use lash_core::{
230        ObservedProcess, ObservedProcessEvent, ObservedWorkItem, ProcessAwaitOutput,
231        ProcessCancelAbility, ProcessCancelAllRequest, ProcessCancelRequest, ProcessCancelSource,
232        ProcessCancelSummary, ProcessDefinitionSummary, ProcessEvent, ProcessEventAppendRequest,
233        ProcessEventAppendResult, ProcessEventType, ProcessExecutionContext, ProcessExternalRef,
234        ProcessHandleDescriptor, ProcessHandleGrant, ProcessHandleSummary, ProcessInput,
235        ProcessLease, ProcessLeaseCompletion, ProcessLifecycleStatus, ProcessListFilter,
236        ProcessListMode, ProcessOpScope, ProcessRecord, ProcessRegistration, ProcessRegistry,
237        ProcessRunHandle, ProcessRuntimeHost, ProcessService, ProcessSessionDeleteReport,
238        ProcessStartOptions, ProcessStartRequest, ProcessStatus, ProcessStatusFilter,
239        ProcessTerminalState, ProcessWake, ProcessWakeDedupeKey, ProcessWakeDelivery,
240        ProcessWakeSpec, ProcessWorkDriver, ProcessWorkObserver, ProcessWorkPoke,
241        ProcessWorkRunner, ProcessWorkSnapshot, SessionScope, SessionScopeId,
242        lashlang_process_event_types,
243    };
244}
245
246pub mod durability {
247    pub use lash_core::{
248        DurableProcessWorker, DurableProcessWorkerConfig, EffectHost, InlineEffectHost, Residency,
249        RuntimeEnvironment, RuntimeHostConfig, TerminationPolicy,
250    };
251}
252
253pub mod runtime {
254    pub use crate::core::AdvancedLashCoreBuilder;
255    pub use lash_core::runtime::{
256        AssembledTurn, DirectCompletionClient, EmbeddedRuntimeHost, EventSink, ExecutionScope,
257        InlineRuntimeEffectController, LashRuntime, LlmAttachmentSpec, LlmRequestSpec,
258        NoopEventSink, NoopTurnActivitySink, ProcessCommand, ProcessEffectOutcome, QueuedWorkPoke,
259        QueuedWorkRunHandle, QueuedWorkRunOutcome, QueuedWorkRunRequest, QueuedWorkRunner,
260        RuntimeEffectCommand, RuntimeEffectController, RuntimeEffectControllerError,
261        RuntimeEffectEnvelope, RuntimeEffectKind, RuntimeEffectLocalExecutor, RuntimeEffectOutcome,
262        RuntimeEnvironmentBuilder, RuntimeError, RuntimeErrorCode, RuntimeHandle,
263        RuntimeInvocation, RuntimeObservation, RuntimeScope, RuntimeTurnPhase,
264        RuntimeTurnPhaseProbe, ScopedEffectController, TurnContext,
265    };
266    pub use lash_core::{
267        PersistentRuntimeServices, PluginMessage, ProtocolSessionExtensionHandle,
268        ProtocolTurnOptions, SessionHandle, SessionPolicy, SessionSnapshot, TurnCause, TurnFinish,
269        TurnOutcome, TurnStop, render_turn_causes_prompt,
270    };
271}
272
273pub mod prompt {
274    pub use lash_core::{
275        PromptBuiltin, PromptContribution, PromptContributionGate, PromptLayer, PromptSlot,
276        PromptTemplate, PromptTemplateEntry, PromptTemplateSection, default_prompt_template,
277    };
278}
279
280pub mod tracing {
281    pub use lash_core::{
282        JsonlTraceSink, TraceAttachment, TraceBranchSelection, TraceContentBlock, TraceError,
283        TraceEvent, TraceLabelMetadata, TraceLashlangChildExecution, TraceLashlangEdgeSelection,
284        TraceLashlangExecutionEvent, TraceLashlangExecutionIdentity, TraceLashlangGraph,
285        TraceLashlangGraphChildLink, TraceLashlangGraphEdge, TraceLashlangGraphNode,
286        TraceLashlangGraphStore, TraceLashlangMap, TraceLashlangMapEdge, TraceLashlangMapNode,
287        TraceLashlangNodeStatus, TraceLashlangStatus, TraceLlmMessage, TraceLlmRequest,
288        TraceLlmResponse, TracePromptComponent, TraceProviderStreamEvent, TraceRecord,
289        TraceRuntimeScope, TraceRuntimeStreamEvent, TraceRuntimeSubject, TraceSinkError,
290        TraceTokenUsage, TraceToolSpec,
291    };
292    pub use lash_trace::{StderrTraceSink, TeeTraceSink, TraceContext, TraceLevel, TraceSink};
293}
294
295/// Test helpers for embedders. Enable with `lash = { ..., features = ["testing"] }`
296/// to script model responses in integration tests without a live provider.
297#[cfg(any(test, feature = "testing"))]
298pub mod testing;
299
300pub mod provider {
301    pub use lash_core::provider::{
302        ProviderRateLimitPolicy, ProviderReliability, ProviderRetryPolicy,
303    };
304    pub use lash_core::{
305        LlmTimeouts, Provider, ProviderComponents, ProviderFactory, ProviderHandle,
306        ProviderModelPolicy, ProviderOptions, ProviderSpec, RequestTimeout, StaticModelPolicy,
307    };
308}
lash/lib.rs

lash/
lib.rs
