Crate everruns

Expand description

The application-facing crate for the Everruns Framework.

Build agents, attach provider configuration, select model ids, add typed tools, run isolated multi-turn sessions, bind backend-owned workspace heads through Environments, read bounded history, resume typed session identities, observe events, cancel work, and inspect the next model context without constructing an execution host. Default features stay offline; the deterministic simulator needs no credentials or network. The default registry advertises only portable capabilities; hosted knowledge, delegation, task, hook, and platform-management implementations require an explicit Everruns Platform host.

everruns is the primary Rust library in the Everruns ecosystem. Ordinary applications begin here. Engine hosting adapters use hosting::SessionHosting and hosting::spi without a direct Core dependency. Embedding hosts that keep their own capabilities, provider resolution, recovery budgets, MCP credentials and observers compose them with hosting::services. Separately composed low-level execution hosts select the host, engine, builtins, MCP or AG-UI features of everruns-core, with everruns-contracts for neutral extension types and everruns::batteries for concrete integration presets.

§Example

Run one simulated turn, importing only everruns:

use everruns::{Agent, Engine, Model};

let agent = Agent::builder()
    .instructions("You are a helpful assistant.")
    .model(Model::simulated("4"))
    .build()
    .expect("valid agent");
let engine = Engine::new();
let result = engine.create(agent).send_and_wait("What is 2 + 2?").await?;
assert!(result.success);
assert_eq!(result.response, "4");

Re-exports§

pub use decisions::Answers;
pub use decisions::Decision;
pub use decisions::Decisions;
pub use decisions::DecisionsError;
pub use llm::Completion;
pub use llm::CompletionError;
pub use models::CatalogError;
pub use models::ModelInfo;

Modules§

approval: Stability: alpha — may change without a major bump; see stability. Stability: alpha — may change without a major bump; see stability.
ask_user: Stability: stable — no breaking change without a major bump; see stability. Stable host contract and values for structured in-process questions.
batch: Stability: alpha — provider-native offline model requests. Stability: alpha — explicit provider-native offline completions.
batteries: Default integration and driver wiring selected by Framework features. Framework batteries: default capability and outbound-transport wiring.
capability: Stable service-provider interface for advanced, code-defined capabilities.
conversation: What an agent said to the conversation: the one rule every surface uses to pick an agent’s answer, so commentary never counts as a reply.
decisions: Stability: alpha — may change without a major bump; see stability. Stability: alpha — may change without a major bump; see stability.
execution_api: Wire types of the Agent Execution API, the per-agent session API that the everruns server and serve both expose.
hosting: Coherent session hosting below Engine.
llm: Stability: stable — no breaking change without a major bump; see stability. Stability: stable — no breaking change without a major bump; see stability.
models: Stability: alpha — may change without a major bump; see stability. Stability: alpha — may change without a major bump; see stability.
prelude: The common path: everything needed to describe an agent and run turns.
providers: Real LLM provider configuration for the facade.
stability: Stability tiers and the marking convention. Stability tiers for the framework surface: what each marker promises.
work: Session-owned background work, scheduling, cancellation, and wakes. Session-owned background work and wakes.

Structs§

Agent: The immutable, validated description of an agent.
AgentBuilder: Fluent builder behind Agent::builder.
AgentInstructionsConfig
AgentManifest: Authored values only: no organisation, agent, model, harness or channel IDs.
AgentPackage: An ID-free manifest and materialized assets. Provider credentials, custom tool implementations and channel transports are supplied by the host.
AgentStartContext: Context passed to an on_agent_start handler.
BearerAuth: Static Authorization: Bearer … authentication.
CancellationToken: A handle for cancelling an in-flight turn.
CapabilityChange: The effect of a session capability activation or deactivation.
CapabilityRef: A reference to a capability implementation plus per-agent JSON.
CapabilitySpec: The normalized value produced by IntoCapability.
CausalContext: Bounded durable causal identities, independent of any exporter. Ordered, deduplicated causes. No OpenTelemetry dependency is needed to persist these across volatile, SQLite and Platform execution.
CausalLink: Bounded durable causal identities, independent of any exporter. A validated trace/span identity, with no baggage or vendor state.
CommandArgument: An argument of a CommandInfo.
CommandInfo: A slash command contributed by an active capability.
CommandOutput: The result of a capability command run through Session::run_command.
CompactionConfig: Application-facing context-compaction policy.
CompletionContext: Context passed to an on_completion handler.
CompletionRequest: A host-curated, tool-less completion request for Session::complete.
ComputeCapabilities: What a target can actually do.
Containment: What a command may touch, and who enforces it.
ContextMessage: One message in an inspected session context.
Controls: Runtime controls for message processing
CostTier: A pricing tier that activates above a context token threshold. For example, OpenAI charges higher rates for prompts exceeding 200K tokens.
CredentialFormSchema: Describes the form fields and instructions for entering a credential.
DecisionDriverCapabilities: What a driver can do, declared up front.
DecisionOutcome: The result of one evaluation.
DecisionRequest: One evaluation: state plus the questions to ask about it.
DecisionRouter
DecisionUsage: Token usage for one request.
DiscoveredModel: Model information discovered from a provider’s list_models API
DreamBudget: Background memory consolidation configuration.
DreamDestination: Background memory consolidation configuration.
DreamTrigger: Background memory consolidation configuration.
DreamingConfig: Background memory consolidation configuration.
DriverConfig: Everything a DriverFactory receives to build a driver instance.
DriverDescriptor: A registered provider driver: identity, declared services, the credential shape its providers must supply, and per-service factories.
DriverId: Open string identifier retained as the 0.17.x integration-kind name.
DriverRegistry: Registry for LLM drivers
Engine: Application-owned session execution engine.
EngineBuilder: Configures an application-owned Engine.
EnvCredentialProvider: A CredentialProvider that reads a driver’s declared variables from the process environment.
Environment: Session execution resources: the workspace head every file tool addresses, the compute that runs commands against it, and what that compute may touch.
EnvironmentBuilder
EnvironmentSessionBuilder: A not-yet-running Session with its Environment selected.
EventFilter: Selects the event types delivered to an EventListener.
EventStream: A live feed of SessionEvents for one Session.
ExecRequest: One command to run.
ExecResult: What one command did.
FileSystem: Activate the session filesystem with its default configuration.
FormField: A single form field.
FunctionTool: A custom agent tool backed by an async function or closure.
Harness: A reusable description of what an agent runs on.
HarnessBuilder: Fluent builder behind Harness::builder.
HarnessEnvironmentSessionBuilder: A not-yet-running Session with its Harness and Environment selected.
HarnessSessionBuilder: A not-yet-running Session with its Harness selected.
HistoryCursor: Opaque continuation token for a stable session-history snapshot.
HistoryCursorParseError: A string could not be parsed as a HistoryCursor.
HistoryPage: One bounded page of a session conversation.
HistoryPages: Lazy, fused reader for all pages in one stable history snapshot.
HistoryQuery: Owned builder for one bounded, stable session-history snapshot.
HookFailure: A lifecycle handler failure surfaced by the Framework.
HostBackends: Non-filesystem backend bundle supplied to an execution host.
ImageContentPart: Image content part (base64 or URL)
InitialFile: Starter file copied into a new session from an agent or harness.
InputMessage: Input message for creating a new message
InterruptedTurn: A turn a process exit cut off. See Session::interrupted_turn.
ListenerStats: Delivery counters for one Engine listener.
LlmCallConfig: Configuration for an LLM call
LlmCallConfigBuilder: Builder for LlmCallConfig with fluent API
LlmCompletionMetadata: Metadata about LLM completion Contains token usage and completion information from the LLM response.
LlmDecisionDriver: Answers DecisionRequests with the deployment’s utility LLM.
LlmError: LLM provider error with a semantic kind attached by the driver.
LlmResponse: Response from an LLM call (non-streaming)
LlmSimConfig: Configuration for the LlmSim driver.
McpServer: A scoped MCP server available to an agent.
Model: A model selected for an Agent.
ModelCost: Cost information for the model (per million tokens)
ModelLimits: Token limits for the model
ModelModalities: Model modalities for input and output
ModelProfile: LLM Model Profile describing model capabilities Based on models.dev structure (https://models.dev/api.json)
NativePrimitives: Which primitives a vendor answers without translation.
ObserverReport: Result of a deadline-bounded Engine observer shutdown.
ObserverStats: Snapshot of Engine observer delivery counters.
PackageChange: Semantic change; file bodies are represented by digests, never dumped.
PackageDiagnostic: A field-addressed diagnostic, shared by local validation and import APIs.
PackageError
PluginError: Failure while reading or compiling a local plugin directory.
ProviderAuthRequest: Immutable request material available to an authentication implementation.
ProviderCredentials: Credentials resolved for a single driver.
ProviderEndpoint: Endpoint and authentication policy handed to a wire driver.
ProviderKey: Open, normalized identity used by model specifications to select a provider.
ReasoningConfig: Reasoning configuration for the model
ReasoningContentPart: One provider-issued reasoning artifact, ordered in Message.content alongside text and tool calls.
RunOptions: Options controlling a single Session::run_with.
SentMessage: Receipt returned once Session::send accepts a message.
Session: A live, multi-turn conversation with an Agent.
SessionContext: The effective context a session will send to its model on the next turn.
SessionEvent: A single observed event from a running Session.
SessionEventCursor: A validated, session-scoped continuation for canonical event replay. Snapshot-bound continuation cursor for canonical event replay.
SessionEventPage: One bounded snapshot of canonical session events.
SessionMessage: One application-facing message in a HistoryPage.
SimToolCall: A single tool call inside a scripted turn.
SingleDriverService: Serve a single driver as a DecisionsService.
Skills: Activate workspace skill discovery with its default configuration.
StatelessTodoList: Activate the conversation-backed todo list with its default configuration.
StaticHeaderAuth: Static authentication carried in one named header.
ToolAnswer: A caller’s durable answer to one outstanding client tool request.
ToolCall: Tool call from LLM response
ToolCallContext: What a FunctionTool handler knows about the call it is serving.
ToolEndContext: Context passed to an on_tool_end handler.
ToolInfo: A model-visible tool in an inspected session context.
ToolResponse: A ready-to-return structured tool result.
ToolSearch: Model-adaptive deferred tool-loading configuration.
ToolStartContext: Context passed to an on_tool_start handler.
Turn: The outcome of a single Session::run turn.
TurnHandle: A cloneable handle to one active or completed turn.
TurnStartContext: Context passed to an on_turn_start handler.
Workspace: One logical workspace opened through a backend.
WorkspaceBackendId: Stable, backend-defined SPI identifier.
WorkspaceBinding: Backend-owned data sufficient to reopen the exact recorded head.
WorkspaceCheckpoint: Backend-neutral checkpoint metadata.
WorkspaceDescriptor: Backend-neutral identity and base metadata for a logical workspace.
WorkspaceDiff: Backend-neutral diff summary for one mutable head.
WorkspaceHead: One stable, reopenable mutable view of a workspace.
WorkspaceHeadBuilder: Builder for explicit isolated or shared heads.
WorkspaceHeadDescriptor: Backend-neutral identity and base metadata for a head.
WorkspaceHeadId: Stable identity of one mutable workspace head.
WorkspaceHeadRequest: Request to create or fork one head.
WorkspaceHeadResource: A backend-produced head resource before the Framework attaches lifecycle.
WorkspaceHeadStatus: Backend-neutral mutable-head status.
WorkspacePolicy: A validated, composable workspace access policy.
WorkspacePolicyBuilder: Builder for a custom WorkspacePolicy.
WorkspacePolicyError: Invalid policy configuration or a denied workspace operation.
WorkspaceProviderId: Stable, backend-defined SPI identifier.

Enums§

AgentLoopError: Errors that can occur during agent loop execution
AttachError: Why Session::attach did not keep a file.
BillingPressureReason: Machine-readable reason for provider billing pressure.
BuildError: Why an AgentBuilder could not produce an Agent.
CancelError: Why a turn handle could not cancel its turn.
CapabilityRegistrationError: Why Engine::register_capability refused a capability.
CompactionStrategy: Strategy used when a conversation outgrows the model context.
ComputeError: Why compute could not do what was asked.
ComputeKind: The shape of a compute target, independent of any one provider.
ContainmentLevel: How much of the host a command may reach.
ContentPart: A part of message content - can be text, image, image_file, tool_call, or tool_result
DecisionAnswer: One typed answer.
DecisionQuestion: One typed question.
DreamCommitMode: Background memory consolidation configuration.
DreamTriggerMode: Background memory consolidation configuration.
Durability: How much of the working filesystem survives losing the compute.
EnvCredentialError: Why a driver could not be configured from the environment.
EnvironmentError: Why an Environment could not be assembled.
EventStreamError: Why an EventStream could not deliver the next event losslessly.
ExecutionPhase: Execution phase for assistant messages in multi-step tool-calling flows.
FieldType: Input field type for rendering.
HarnessBuildError: Why a HarnessBuilder could not produce a Harness.
HistoryError: Why a bounded session-history request could not be completed.
HookPoint: A typed Framework lifecycle point.
HookRecovery: How an unfinished hook invocation recovers after executor loss.
LlmContentPart: A single content part within a message
LlmErrorKind: Semantic classification of an LLM provider error, assigned by the driver at the provider boundary where the HTTP status and response body are still available. Downstream consumers prefer this over re-parsing error strings; LlmErrorKind::Other falls back to string classification (classify_runtime_error_message) so untyped errors keep working.
LlmStreamEvent: Events emitted during LLM streaming
MessageRole: Message role in the conversation
Modality: Modality type (text, image, audio, video)
ModelVendor: Vendor / brand that authored a model. Independent of the provider type that serves it (the same model may be offered by several providers or gateways). Primarily drives UI iconography.
NetworkPolicy: Outbound network policy for commands.
OnExhausted: Behavior when a scripted config has consumed all turns.
PackageFormat
PhaseSource: Where a message’s ExecutionPhase came from.
ReasoningEffort: Reasoning effort level for models that support it
ReasoningText: Readable reasoning text, in the form the provider actually exposes.
ResumeError: Why an existing Framework session could not be resumed.
RunError: Why a Session::run could not complete.
SendDisposition: How Session::send routed an accepted message.
SessionControlError: Why a session control or query was refused.
SessionEnvironmentError: Why an Environment could not be fixed to a Session.
SessionEventKind: The event-specific payload of a SessionEvent.
SimError: Error to inject for a scripted turn.
SimTurn: A single scripted assistant turn.
Tool: A closure-backed function tool accepted by AgentBuilder::tool.
ToolDefinition: Tool definition in agent configuration
TurnStopReason: Stable reason a turn stopped, independent of provider-specific strings.
WorkspaceError: Errors exposed by workspace backends and lifecycle operations.
WorkspaceHeadAccess: Whether a head is intended for one session or intentionally shared.

Constants§

COMPLETION_PURPOSE_KEY: Provider metadata key CompletionRequest::purpose sets.
EVENT_STREAM_CAPACITY: Capacity of the per-session broadcast channel that backs EventStream.
MAX_COMPLETION_MESSAGES: Most messages a CompletionRequest may carry.
MAX_COMPLETION_SYSTEM_PROMPTS: Most system prompts a CompletionRequest may carry.
OBSERVER_QUEUE_CAPACITY: Default number of pending events retained for each Engine listener.

Traits§

ChatDriver: Trait for LLM drivers
Compute: A target that can run commands against a workspace head.
ComputeSession: A connected target, ready to run commands.
CredentialProvider: A source of provider credentials, injected by the caller.
DecisionDriver: One vendor’s transport for typed decisions.
DecisionsService: Host-owned service answering typed questions.
EventListener: Receives projected events from every session owned by an Engine.
IntoCapability: Convert an application value into one capability registration.
IntoHookResult: Convert a lifecycle handler’s output into the Framework hook result.
IntoTool: Conversion into a Tool for AgentBuilder::tool.
IntoToolResult: Converts a handler’s success value into the engine’s tool-result shape.
ProviderAuth: Resolves authentication for each outbound provider request.
WorkspaceBackend: Open interface for physical workspace implementations.
WorkspaceProvider: Open interface for physical workspace implementations.

Functions§

provider_from_env: Build a chat Provider for a driver from the variables that driver declares.

Type Aliases§

BoxedChatDriver: Boxed chat driver for dynamic dispatch
InMemoryEngine: Compatibility name for the application-owned process-local engine.
LlmMessageDeprecated: Pre-0.31 name of Message.
LlmMessageContentDeprecated: Pre-0.31 name of MessageContent.
LlmMessageRoleDeprecated: Pre-0.31 name of MessageRole.
LlmResponseStream: Type alias for the LLM response stream
MessageId: Message ID
Provider: Public application-facing name for a runtime provider.
SessionId: Session ID
TurnId: Turn ID
WorkspaceId: Workspace ID (org-scoped named Workspace)

Attribute Macros§

tool: Turn a typed async function into an agent tool.

Crate everruns

Crate everruns Copy item path

§Example

Re-exports§

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Attribute Macros§

Crate everruns