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; advanced execution hosts use everruns plus everruns-host and focused sibling crates.

§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.
capability: Stable service-provider interface for advanced, code-defined capabilities.
decisions: Stability: alpha — may change without a major bump; see stability. Stability: alpha — may change without a major bump; see stability.
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
AgentStartContext: Context passed to an on_agent_start handler.
BearerAuth: Static Authorization: Bearer … authentication.
CancellationToken: A handle for cancelling an in-flight turn.
CapabilityRef: A reference to a capability implementation plus per-agent JSON.
CapabilitySpec: The normalized value produced by IntoCapability.
CompactionConfig: Application-facing context-compaction policy.
CompletionContext: Context passed to an on_completion handler.
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.
DecisionOutcome: The result of one evaluation.
DecisionRequest: One evaluation: state plus the questions to ask about it.
DiscoveredModel: Model information discovered from a provider’s list_models API
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
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.
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)
ObserverReport: Result of a deadline-bounded Engine observer shutdown.
ObserverStats: Snapshot of Engine observer delivery counters.
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.
SessionMessage: One application-facing message in a HistoryPage.
SimToolCall: A single tool call inside a scripted turn.
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.
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
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.
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.
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.
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.
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.
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§

EVENT_STREAM_CAPACITY: Capacity of the per-session broadcast channel that backs EventStream.
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.
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
Provider: Public application-facing name for a runtime provider.
SessionId: Session ID
WorkspaceId: Workspace ID (org-scoped named Workspace — see knowledge/runtime-resources/workspace.md)

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