everruns_core/
lib.rs

1//! Core agent abstractions for Everruns.
2//!
3//! `everruns-core` is the shared contract crate for the
4//! [Everruns](https://everruns.com) ecosystem. It defines the runtime-facing
5//! types used by embedded hosts, workers, provider drivers, integrations, and
6//! the control plane.
7//!
8//! The crate is deliberately storage-agnostic. Agent execution is expressed in
9//! terms of traits such as [`MessageRetriever`], [`ToolExecutor`],
10//! [`EventEmitter`], and [`LlmProviderStore`], while host crates decide whether
11//! those traits are backed by memory, PostgreSQL, gRPC, or another system.
12//!
13//! # Main Surfaces
14//!
15//! - Agent, harness, session, message, event, and typed ID models
16//! - Capability and tool traits for composing agent behavior
17//! - Provider-neutral LLM messages, streams, and driver registration
18//! - Context assembly for the shared `input -> reason -> act` execution flow
19//! - In-memory helpers and `llmsim` for deterministic tests and examples
20//!
21//! # Example
22//!
23//! ```ignore
24//! use everruns_core::{CapabilityRegistry, DriverRegistry, PlatformDefinition};
25//! use everruns_core::capabilities::TestMathCapability;
26//!
27//! let mut capabilities = CapabilityRegistry::new();
28//! capabilities.register(TestMathCapability);
29//!
30//! let platform = PlatformDefinition::new(capabilities, DriverRegistry::new());
31//! assert!(platform.capability_registry().get("test_math").is_some());
32//! ```
33
34// Runtime types (tool definitions, capability types)
35pub mod capability_types;
36pub mod tool_fingerprint;
37pub mod tool_types;
38
39// User-defined hooks (see specs/user-hooks.md)
40pub mod hook_adapter;
41pub mod hook_dispatch;
42pub mod hook_executor;
43pub mod lifecycle_hooks;
44pub mod user_hook_types;
45
46// Deployment configuration
47pub mod deployment;
48pub mod egress;
49pub mod email;
50pub mod exec_tool_result;
51pub mod utility_llm;
52
53// Feature flags
54pub mod feature_flags;
55pub mod localization;
56
57// Telemetry (OpenTelemetry with gen-ai semantic conventions)
58pub mod telemetry;
59pub mod tool_narration;
60
61// Event listeners (pluggable observability backends)
62pub mod event_listeners;
63
64// Error reporter (vendor-neutral embedder hook)
65pub mod error_reporter;
66
67// Observation backends (OTel, etc.)
68pub mod observation;
69
70// Typed ID system (type-safe prefixed identifiers)
71// See specs/id-schema.md for specification
72pub mod typed_id;
73
74// Audit logging types and trait (EVE-226)
75pub mod audit;
76
77// Budget types (budgets, ledger, rules, actions)
78pub mod background;
79pub mod budget;
80
81// Domain entity types
82// These are DB-agnostic entity types used by both API and worker
83pub mod agent;
84pub mod agent_identity;
85pub mod app;
86pub mod capability_dto;
87pub mod connection_provider;
88pub mod eval;
89pub mod events;
90pub mod harness;
91pub mod leased_resource;
92pub mod llm_model_profiles;
93pub mod llm_models;
94pub mod mcp_proxy;
95pub mod mcp_server;
96pub mod memory_store;
97pub mod model_router;
98pub mod network_access;
99pub mod organization;
100pub mod payment;
101pub mod principal;
102pub mod reporting;
103pub mod session;
104pub mod session_file;
105pub mod session_resource;
106pub mod session_sandbox;
107pub mod session_schedule;
108pub mod session_sqldb;
109pub mod skill;
110pub mod system_allowlist;
111pub mod volume;
112
113// Multi-platform channel abstractions (thread context, delivery, routing)
114pub mod channel;
115
116// Permissions model (policies, rules, caller context)
117pub mod permissions;
118pub mod progress_reporting;
119pub mod resource_names;
120
121// URL validation for SSRF prevention (shared utility)
122pub mod url_validation;
123
124pub mod atoms;
125pub mod capabilities;
126pub mod command;
127pub mod config_layer;
128pub mod context_report;
129pub mod dependency_blocker;
130pub mod error;
131pub mod llm_driver_helpers;
132pub mod llm_driver_registry;
133pub mod llm_retry;
134pub mod message;
135pub mod message_filter;
136pub mod message_retriever;
137pub mod openai_protocol;
138pub mod openresponses_protocol;
139pub mod openresponses_types;
140pub mod outline;
141pub mod output_guardrail;
142pub mod platform_definition;
143pub mod platform_store;
144pub mod resource_ownership;
145pub mod runtime_agent;
146pub mod runtime_context;
147pub mod tool_output_sanitizer;
148pub mod tools;
149pub mod traits;
150pub mod truncation_info;
151pub mod user_facing_error;
152
153// In-memory implementations for examples and testing
154pub mod memory;
155
156// LLM Simulator driver for testing
157pub mod llmsim_driver;
158
159// In-memory agentic loop for testing and prototyping
160pub mod in_memory_loop;
161
162// Turn orchestration (state machine, context, outcomes)
163pub mod turn;
164
165// Note: LLM Driver implementations (AnthropicLlmDriver, OpenAILlmDriver) are now in
166// separate crates (everruns-anthropic, everruns-openai) that depend on everruns-core.
167// This enables dependency inversion - provider crates register their drivers at startup.
168
169// Re-exports for convenience
170pub use config_layer::{
171    AgentConfigOverlay, merge_capabilities, merge_initial_files, normalize_initial_file_path,
172};
173pub use error::{AgentLoopError, Result, StoreResultExt, from_json, json_val};
174pub use message::{
175    ContentPart, ContentType, Controls, ExternalActor, ImageContentPart, ImageFileContentPart,
176    InputContentPart, Message, MessageRole, ReasoningConfig, TextContentPart, ToolCallContentPart,
177    ToolResultContentPart,
178};
179pub use message_filter::{
180    ExcludedNoticeTransform, FilterContext, InjectedMessage, InjectionPosition, MessageFilter,
181    MessageFilterProvider, MessageQuery, PrependTransform,
182};
183pub use message_retriever::{InputMessage, MessageRetriever};
184pub use runtime_agent::{RuntimeAgent, RuntimeAgentBuilder};
185pub use runtime_context::{
186    AssembledTurnContext, ResolvedRuntimeCapabilities, assemble_turn_context, inspect_turn_context,
187    resolve_runtime_capabilities,
188};
189pub use traits::{
190    DisabledSessionFileSystemFactory, DurableToolResultStore, EventEmitter, HarnessStore,
191    ImageResolver, KeyInfo, LeasedResourceStore, LlmProviderStore, ModelWithProvider,
192    NoopDurableToolResultStore, NoopEventEmitter, NoopStreamHeartbeater, OutboundToolRateLimiter,
193    ResolvedImage, SecretInfo, SessionFileStore, SessionFileSystem, SessionFileSystemFactory,
194    SessionFileSystemFactoryContext, SessionMutator, SessionResourceRegistry, SessionSqlDbStoreRef,
195    SessionStorageStore, SessionStore, StreamHeartbeater, StreamProgress, ToolCallClaimResult,
196    ToolContext, ToolExecutor, UserConnectionResolver,
197};
198pub use user_facing_error::{
199    UserFacingError, UserFacingErrorContext, UserFacingErrorFields, classify_runtime_error_message,
200    codes as user_facing_error_codes, trim_error_chain_prefixes,
201};
202
203// Memory store re-exports
204pub use memory_store::{
205    Memory, MemoryContentPart, MemoryImagePart, MemoryKind, MemoryLimits, MemoryQuery,
206    MemoryStoreBackend, MemoryStoreEntity, MemoryTextPart,
207};
208
209// Channel abstraction re-exports
210pub use channel::{
211    ChannelDeliveryAdapter, ChannelReplyMode, DeliveryContext as ChannelDeliveryContext,
212    DeliveryResult as ChannelDeliveryResult, InboundAttachment, InboundChannelEvent,
213    OutboundChannelMessage, Participant, SessionRoutingStrategy, ThreadContext,
214};
215
216// Platform store re-exports
217pub use platform_store::{PlatformMessage, PlatformStore};
218pub use resource_ownership::{
219    LEASED_RESOURCE_EXTERNAL_ID_KEY, LEASED_RESOURCE_ID_KEY, LEASED_RESOURCE_PROVIDER_KEY,
220    LEASED_RESOURCE_TYPE_KEY, list_owned_external_resource_ids,
221    ownership_tracking_unavailable_error, require_owned_external_resource,
222    resource_not_owned_error, verify_owned_external_resource_if_available,
223};
224
225// Event listener re-exports
226pub use background::{
227    BackgroundEventSink, BackgroundExecutableTool, BackgroundOutcome, BackgroundProgress,
228};
229pub use event_listeners::{CompositeEventListener, EventListener, NoopEventListener};
230
231// Error reporter re-exports
232pub use error_reporter::{
233    ErrorReport, ErrorReporter, ErrorScope, ErrorSeverity, NoopErrorReporter, SharedErrorReporter,
234};
235
236// Outbound egress service re-exports
237pub use egress::{
238    DirectEgressService, DisabledEgressService, EgressByteStream, EgressError, EgressRequest,
239    EgressRequestKind, EgressResponse, EgressResult, EgressService, EgressSigning,
240    EgressStreamResponse,
241};
242pub use system_allowlist::{AllowGroup, SYSTEM_ALLOWLIST_ENABLED_ENV, SystemAllowlist};
243
244// System email re-exports
245pub use email::{
246    DisabledEmailSender, EmailAddress, EmailError, EmailMessage, EmailResult, EmailSender,
247    EmailTag, EmailTemplate, GenericEmailTemplate, NoopEmailSender, RenderedEmail,
248    ResendEmailConfig, ResendEmailSender, SYSTEM_EMAIL_FROM, SentEmail, SystemEmailConfig,
249    system_email_from,
250};
251pub use utility_llm::{
252    DisabledUtilityLlmService, OpenAiUtilityLlmService, SystemUtilityLlmConfig, UTILITY_LLM_MODEL,
253    UTILITY_OPENAI_API_KEY_ENV, UtilityLlmReasoningEffort, UtilityLlmRequest, UtilityLlmService,
254};
255
256// LLM driver types re-exports
257pub use llm_driver_registry::{
258    BoxedLlmDriver, DiscoveredModel, DriverFactory, DriverRegistry, LlmCallConfig,
259    LlmCallConfigBuilder, LlmCompletionMetadata, LlmContentPart, LlmDriver, LlmMessage,
260    LlmMessageContent, LlmMessageRole, LlmResponse, LlmResponseStream, LlmStreamEvent,
261    ProviderConfig, ProviderType,
262};
263
264// LLM retry types re-exports
265pub use llm_retry::{LlmRetryConfig, RateLimitInfo, RateLimitType, RetryMetadata};
266
267// OpenAI Protocol driver (Chat Completions API for backward compatibility)
268pub use openai_protocol::OpenAIProtocolLlmDriver;
269
270// Open Responses Protocol driver (https://www.openresponses.org/)
271// Vendor-neutral API standard, recommended for new projects
272pub use openresponses_protocol::{
273    CompactContent, CompactContentPart, CompactInputItem, CompactOutputItem, CompactRequest,
274    CompactResponse, CompactUsage, OpenResponsesProtocolLlmDriver, compact_output_to_messages,
275    messages_to_compact_input,
276};
277
278// Tool abstraction re-exports
279pub use tools::{
280    EchoTool, FailingTool, SpawnBackgroundTool, Tool, ToolExecutionResult, ToolInternalError,
281    ToolRegistry, ToolRegistryBuilder, ToolResultImage,
282};
283
284// Capability re-exports
285// Connection provider plugin system (API key connections like Daytona)
286pub use connection_provider::{
287    ConnectionFormSchema, ConnectionProvider, ConnectionProviderPlugin, ConnectionProviderRegistry,
288    ConnectionProviderRegistryBuilder, ConnectionType, ConnectionValidation, FieldType, FormField,
289};
290pub use platform_definition::{
291    BuiltInCapabilityDefinition, BuiltInHarnessDefinition, BuiltInHarnessRole, PlatformDefinition,
292    PlatformDefinitionBuilder,
293};
294pub use session_sandbox::{
295    DEFAULT_SESSION_SANDBOX_IDLE_TIMEOUT_SECS, SESSION_SANDBOX_CAPABILITY_ID,
296    SESSION_SANDBOX_SECRET_NAME, SessionSandboxConfig, SessionSandboxExecRequest,
297    SessionSandboxExecResponse, SessionSandboxInitConfig, SessionSandboxInstance,
298    SessionSandboxProvider, SessionSandboxProviderPlugin, SessionSandboxReadFileResponse,
299    SessionSandboxState, SessionSandboxStatus, SessionSandboxStatusResponse,
300    SessionSandboxWriteFileResponse, create_session_sandbox_provider, delete_session_sandbox,
301    delete_session_sandbox_state, ensure_session_sandbox_running, load_session_sandbox_state,
302    pause_session_sandbox, run_session_sandbox_init_if_needed, save_session_sandbox_state,
303    session_sandbox_config_from_capabilities, session_sandbox_tool_hints,
304};
305
306pub use capabilities::SystemPromptContext;
307pub use capabilities::{
308    AUTO_TOOL_SEARCH_CAPABILITY_ID, AddTool, AgentBlueprint, AgentCapabilityConfig,
309    AppliedCapabilities, AutoToolSearchCapability, BlueprintModel, Capability, CapabilityId,
310    CapabilityRegistry, CapabilityRegistryBuilder, CapabilityStatus, CollectedCapabilities,
311    CurrentTimeCapability, DECLARATIVE_CAPABILITY_PREFIX, DeleteFileTool, DependencyError,
312    DivideTool, FileSystemCapability, GetCurrentTimeTool, GetForecastTool, GetSessionInfoTool,
313    GetWeatherTool, GrepFilesTool, HUMAN_INTENT_CAPABILITY_ID, HumanIntentCapability,
314    INFINITY_CONTEXT_CAPABILITY_ID, InfinityContextCapability, IntegrationPlugin,
315    ListDirectoryTool, MAX_RESOLVED_CAPABILITIES, MCP_CAPABILITY_PREFIX, McpCapability,
316    MountAccess, MountDirectoryBuilder, MountEntry, MountPoint, MountSource, MultiplyTool,
317    NoopCapability, OPENAI_TOOL_SEARCH_CAPABILITY_ID, OpenAiToolSearchCapability,
318    PlatformManagementCapability, QueryHistoryTool, ReadFileTool, ResearchCapability,
319    ResolvedCapabilities, RiskLevel, SampleDataCapability, SessionCapability,
320    SessionSandboxCapability, SessionSqlDatabaseCapability, SqlExecuteTool, SqlQueryTool,
321    SqlSchemaTool, StatFileTool, StatelessTodoListCapability, SubtractTool, TestMathCapability,
322    TestWeatherCapability, ToolCallHook, ToolDefinitionHook, WriteFileTool, WriteSessionTitleTool,
323    WriteTodosTool, apply_capabilities, collect_capabilities, collect_capabilities_with_configs,
324    compute_features, declarative_capability_id, declarative_capability_info, get_dependencies,
325    hydrate_declarative_capability_config, is_declarative_capability, is_mcp_capability,
326    mcp_capability_id, parse_declarative_capability_id, parse_mcp_capability_id,
327    resolve_dependencies, validate_declarative_capability_definition,
328};
329pub use capabilities::{
330    AttachSkillCapability, SKILL_CAPABILITY_PREFIX, SKILLS_CAPABILITY_ID, SKILLS_DISCOVERY_PATH,
331    SkillInstructions, SkillMeta, SkillSource, SkillsCapability, discover_skills_from_entries,
332    is_skill_capability, parse_skill_capability_id, skill_capability_id,
333};
334pub use capabilities::{
335    DeclarativeCapabilityDefinition, DeclarativeCapabilityFile, DeclarativeCapabilitySkill,
336};
337
338// Atoms re-exports (stateless atomic operations)
339pub use atoms::{
340    ActAtom, ActInput, ActResult, Atom, AtomContext, ClientSideToolHook, ConnectionSetupHook,
341    InputAtom, InputAtomInput, InputAtomResult, PostActAction, PostActHook, PostToolExecHook,
342    ReasonAtom, ReasonInput, ReasonResult, ToolCallResult,
343};
344
345// Tool types (runtime types defined in this crate)
346pub use tool_types::{
347    BuiltinTool, ClientSideTool, DeferrablePolicy, SideEffectClass, ToolCall, ToolDefinition,
348    ToolHints, ToolPolicy, ToolResult,
349};
350
351// Note: CapabilityId and CapabilityStatus are re-exported via capabilities module
352
353// Domain entity re-exports
354// Note: LlmProvider entity is in llm_models module. Import as: everruns_core::llm_models::LlmProvider
355pub use agent::{
356    Agent, AgentStatus, AgentVersion, AgentVersionChangeKind, MAX_ADDRESSABLE_NAME_LEN,
357    generate_agent_public_id, validate_addressable_name, validate_agent_public_id,
358};
359pub use agent_identity::{AgentIdentity, AgentIdentityStatus};
360pub use app::{
361    A2aChannelConfig, AgUiChannelConfig, AgUiToolVisibility, AgentVersionPolicy, App, AppChannel,
362    AppEndpointAuthConfig, AppEndpointAuthMode, AppEndpointAuthProviderConfig,
363    AppEndpointAuthRequirements, AppStatus, ChannelType, FcpChannelConfig, SessionStrategy,
364    SlackChannelConfig, SlackReplyMode,
365};
366pub use capability_dto::{AgentCapability, CapabilityInfo};
367pub use context_report::{
368    ContextReportContribution, ContextReportSection, SessionContextReport,
369    build_session_context_report, build_session_context_report_from_generation,
370};
371pub use events::{
372    ACT_COMPLETED, ACT_STARTED, ActCompletedData, ActStartedData, CONTEXT_COMPACTED,
373    CONTEXT_COMPACTING, CompactionReason, CompactionStepData, ContextCompactedData,
374    ContextCompactingData, Event, EventBuilder, EventContext, EventData, EventRequest,
375    FILE_WRITTEN, FileWrittenData, INPUT_MESSAGE, InputMessageData, LLM_GENERATION,
376    LlmCompactionInfo, LlmGenerationData, LlmGenerationMetadata, LlmGenerationOutput, LlmRetryInfo,
377    ModelMetadata, OUTPUT_MESSAGE_COMPLETED, OUTPUT_MESSAGE_DELTA, OUTPUT_MESSAGE_REPLACED,
378    OUTPUT_MESSAGE_STARTED, OutputMessageCompletedData, OutputMessageDeltaData,
379    OutputMessageReplacedData, OutputMessageStartedData, REASON_COMPLETED, REASON_ITEM,
380    REASON_STARTED, REASON_THINKING_COMPLETED, REASON_THINKING_DELTA, REASON_THINKING_STARTED,
381    ReasonCompletedData, ReasonItemData, ReasonStartedData, ReasonThinkingCompletedData,
382    ReasonThinkingDeltaData, ReasonThinkingStartedData, SESSION_ACTIVATED, SESSION_IDLED,
383    SESSION_STARTED, SessionActivatedData, SessionIdledData, SessionStartedData,
384    TOOL_CALL_REQUESTED, TOOL_COMPLETED, TOOL_OUTPUT_DELTA, TOOL_PROGRESS, TOOL_STARTED,
385    TURN_CANCELLED, TURN_COMPLETED, TURN_FAILED, TURN_STARTED, TokenUsage, ToolCallRequestedData,
386    ToolCallSummary, ToolCompletedData, ToolOutputDeltaData, ToolProgressData, ToolStartedData,
387    TurnCancelledData, TurnCompletedData, TurnFailedData, TurnStartedData, VALID_EVENT_TYPES,
388};
389pub use harness::{Harness, HarnessStatus, merge_harness, merge_harness_chain};
390pub use leased_resource::{
391    LEASED_RESOURCES_FEATURE, LeasedResource, LeasedResourceStatus, UpsertLeasedResource,
392};
393pub use llm_model_profiles::{get_model_profile, get_model_vendor};
394pub use llm_models::{
395    CostTier, LlmModel, LlmModelCost, LlmModelLimits, LlmModelModalities, LlmModelProfile,
396    LlmModelSource, LlmModelWithProvider, LlmProviderStatus, LlmProviderType, Modality,
397    ModelVendor, ReasoningEffort, ReasoningEffortConfig, ReasoningEffortValue,
398};
399pub use mcp_proxy::{McpProxyTool, McpToolInvoker, build_mcp_proxy_tools};
400pub use mcp_server::{
401    McpContent, McpError, McpServer, McpServerAuthMode, McpServerStatus, McpServerTransportType,
402    McpToolAnnotations, McpToolCallParams, McpToolCallRequest, McpToolCallResponse,
403    McpToolCallResult, McpToolDefinition, McpToolsListRequest, McpToolsListResponse,
404    McpToolsListResult, ScopedMcpServer, ScopedMcpServers, is_mcp_tool,
405    mcp_oauth_provider_id_for_uuid, mcp_oauth_session_secret_name, mcp_tool_name,
406    merge_scoped_mcp_servers, parse_mcp_tool_name, sanitize_mcp_server_name,
407    scoped_mcp_servers_is_empty,
408};
409pub use organization::{
410    ANONYMOUS_USER_EMAIL, ANONYMOUS_USER_ID, ANONYMOUS_USER_NAME, DEFAULT_ORG_ID,
411    DEFAULT_ORG_PUBLIC_ID, OrgMembership, OrgRole, Organization, generate_org_public_id,
412    org_public_id_from_internal, validate_org_public_id,
413};
414pub use payment::{
415    MachinePaymentRequest, MachinePaymentResponse, PaymentAccount, PaymentAttempt, PaymentMethod,
416    PaymentOwnerType, PaymentPolicy, PaymentRail, PaymentStatus,
417};
418pub use principal::{Principal, PrincipalKind, PrincipalStatus, PrincipalSummary};
419pub use session::{Session, SessionStatus, SubagentStatus};
420pub use session_file::{FileInfo, FileStat, GrepMatch, GrepResult, InitialFile, SessionFile};
421pub use session_resource::{
422    RegisterSessionResource, SessionResourceEntry, SessionResourceFilter, SessionResourceStatus,
423};
424pub use session_sqldb::{
425    ColumnSchema, DatabaseInfo, SessionSqlDbError, SessionSqlDbStore, SqlExecuteResult,
426    SqlQueryResult, TableSchema,
427};
428pub use skill::{
429    ParsedSkillMd, Skill, SkillContent, SkillFileEntry, SkillSourceType, SkillStatus, SkillUsage,
430    SkillValidationResult, parse_skill_md, validate_skill_md, validate_skill_name,
431};
432pub use typed_id::{
433    AgentId, AgentIdentityId, AgentVersionId, AppChannelId, AppId, DeclarativeCapabilityId,
434    EvalCaseId, EvalId, EvalResultId, EvalRunId, EventId, ExecId, HarnessId, IdMarker,
435    IdParseError, ImageId, KnowledgeBaseId, KnowledgeEntryId, LeasedResourceId, McpServerId,
436    MemoryId, MemoryStoreId, MessageId, ModelId, NotificationId, OrgId, PaymentAccountId,
437    PaymentAttemptId, PaymentPolicyId, PrincipalId, ProviderId, ScheduleId, SessionId, SkillId,
438    TurnId, TypedId,
439};
440
441// Audit logging re-exports
442pub use audit::{
443    AgentAction, AuditAction, AuditDomain, AuditEvent, AuditEventBuilder, AuditLogger, AuditTarget,
444    ManagementAction,
445};
446
447// Permissions re-exports
448pub use permissions::{
449    Caller, DefaultPermissionResolver, Permission, PermissionResolver, Policy,
450    PolicyConfigResponse, PolicyError, ResourceConfigResponse, Rule, SkillPermissionAction,
451    SkillPermissionPattern, SkillPermissionRule, check_skill_permission, evaluate_policies,
452    evaluate_policies_with, parse_skill_permission_rule, role_has_permission, role_permissions,
453};
454
455// Dependency blocker re-exports
456pub use dependency_blocker::{DependencyBlocker, detect_dependency_blocker};
457
458// URL validation re-exports
459pub use url_validation::{
460    UrlValidationError, is_blocked_ip, validate_safe_url, validate_url_dns_pinned,
461};
462
463// Deployment configuration
464pub use deployment::DeploymentGrade;
465
466// Feature flags
467pub use feature_flags::{
468    API_FEATURE_FLAG_DEFINITIONS, FeatureFlagDefinition, FeatureFlags, InternalFeatureFlags,
469};
470
471// Observation backends
472pub use observation::{BraintrustConfig, BraintrustListener, OtelEventListener};
everruns_core/lib.rs

everruns_core/
lib.rs
