a3s_code_core/
lib.rs

1//! A3S Code Core Library
2//!
3//! Harness-driven runtime for coding agents.
4//!
5//! `Agent` and `AgentSession` are the primary 2.0 API. Lower-level session
6//! runtime state is internal; persistence data flows through `store::SessionData`.
7//!
8//! ## Quick Start
9//!
10//! ```rust,no_run
11//! use a3s_code_core::{Agent, AgentEvent};
12//!
13//! # async fn run() -> anyhow::Result<()> {
14//! // From an ACL-compatible config file path (.acl)
15//! let agent = Agent::new("agent.acl").await?;
16//!
17//! // Create a workspace-bound session
18//! let session = agent.session_async("/my-project", None).await?;
19//!
20//! // Non-streaming
21//! let result = session.send("What files handle auth?", None).await?;
22//! println!("{}", result.text);
23//!
24//! // Streaming (AgentEvent is #[non_exhaustive])
25//! let (mut rx, _handle) = session.stream("Refactor auth", None).await?;
26//! while let Some(event) = rx.recv().await {
27//!     match event {
28//!         AgentEvent::TextDelta { text } => print!("{text}"),
29//!         AgentEvent::End { .. } => break,
30//!         _ => {} // required: #[non_exhaustive]
31//!     }
32//! }
33//! # Ok(())
34//! # }
35//! ```
36//!
37//! ## Disposable Workers
38//!
39//! ```rust,no_run
40//! use a3s_code_core::{Agent, SessionOptions, WorkerAgentSpec};
41//!
42//! # async fn run() -> anyhow::Result<()> {
43//! let agent = Agent::new("agent.acl").await?;
44//! let frontend = WorkerAgentSpec::implementer(
45//!     "frontend-cow",
46//!     "Small verified frontend fixes",
47//! )
48//! .with_model_ref("openai/gpt-4o")
49//! .with_max_steps(24);
50//!
51//! let session = agent.session_async(
52//!     "/my-project",
53//!     Some(SessionOptions::new().with_worker_agent(frontend)),
54//! ).await?;
55//! # Ok(())
56//! # }
57//! ```
58//!
59//! ## Architecture
60//!
61//! ```text
62//! Agent (config-driven facade)
63//!   +-- AgentSession (workspace-bound execution API)
64//!       +-- internal turn runner
65//!       +-- ContextAssembler / ContextProvider
66//!       +-- ToolSelector
67//!       +-- ToolExecutor
68//!       +-- ProgramExecutor (PTC)
69//!       +-- SkillRegistry
70//!       +-- Permission / confirmation
71//!       +-- Trace / artifacts / verification evidence
72//!
73//! Advanced infrastructure:
74//!   +-- optional lane queues for explicit external/hybrid dispatch
75//! ```
76
77pub(crate) mod agent;
78pub(crate) mod agent_api;
79pub mod budget;
80pub(crate) mod child_run;
81pub mod code_intelligence;
82pub mod commands;
83pub(crate) mod compaction;
84pub mod config;
85pub mod context;
86pub mod dynamic_workflow;
87pub mod error;
88pub mod event_protocol;
89pub mod flow_graph;
90pub(crate) mod git;
91pub mod hitl;
92pub mod hooks;
93pub mod host_env;
94pub(crate) mod language;
95pub mod llm;
96pub mod loop_checkpoint;
97pub mod mcp;
98pub mod memory;
99pub mod orchestration;
100pub(crate) mod ordered_parallel;
101pub mod permissions;
102pub mod planning;
103pub mod program;
104pub(crate) mod prompts;
105pub mod queue;
106pub mod release;
107pub mod retention;
108pub(crate) mod retry;
109pub mod rl_trajectory;
110pub mod run;
111pub(crate) mod safety_gate;
112pub mod sandbox;
113#[cfg(feature = "headless-search")]
114pub mod search_runtime;
115pub mod security;
116#[cfg(feature = "serve")]
117pub mod serve;
118pub(crate) mod session_lane_queue;
119pub mod skills;
120pub(crate) mod sse;
121pub mod state_graph;
122pub mod store;
123pub mod subagent;
124pub mod subagent_task_tracker;
125pub mod telemetry;
126#[cfg(feature = "telemetry")]
127pub mod telemetry_otel;
128pub(crate) mod text;
129pub(crate) mod tool_confirmation;
130pub mod tools;
131pub mod trace;
132pub mod verification;
133pub mod workspace;
134
135// Re-export key types at crate root for ergonomic usage
136pub use agent::{AgentEvent, AgentResult};
137pub use agent_api::{
138    Agent, AgentSession, ReadFileOptions, SessionBuilder, SessionOptions, ToolCallResult,
139};
140pub use code_intelligence::{
141    CodeDiagnostic, CodeDiagnosticSeverity, CodeIntelligenceCapabilities, CodeIntelligenceError,
142    CodeIntelligenceLanguageStatus, CodeIntelligenceResult, CodeIntelligenceState,
143    CodeIntelligenceStatus, CodeLocation, CodePosition, CodeQueryResult, CodeRange, CodeSymbolKind,
144    DocumentRevision, DocumentSnapshot, DocumentSymbol, LanguageId, LocalCodeIntelligence,
145    NavigationKind, SymbolInformation, WorkspaceCodeIntelligence,
146};
147pub use config::{
148    AutoDelegationConfig, CodeConfig, ModelConfig, ModelCost, ModelLimit, ModelModalities,
149    OsConfig, ProviderConfig,
150};
151pub use dynamic_workflow::{
152    dynamic_workflow_store_path, DynamicWorkflowRuntime, DynamicWorkflowScriptLimits,
153    DynamicWorkflowTool, DYNAMIC_WORKFLOW_STORE_RELATIVE_PATH,
154};
155pub use error::SessionBuildResource;
156pub use error::{CodeError, Result};
157pub use event_protocol::{
158    run_event_envelope_v1, AgentEventProjectionV1, AgentEventTypeV1, EventEnvelopeV1,
159    EventProtocolError, AGENT_EVENT_TYPES_V1, EVENT_ENVELOPE_V1_VERSION,
160};
161pub use flow_graph::{
162    run_object_id as flow_run_object_id, step_object_id as flow_step_object_id,
163    FileFlowDecisionLedger, FlowDecision, FlowDecisionClaimOutcome, FlowDecisionDispatchError,
164    FlowDecisionDispatcher, FlowDecisionHealthSnapshot, FlowDecisionHealthStatus,
165    FlowDecisionLedger, FlowDecisionRequest, FlowDecisionSink, FlowDecisionStep,
166    FlowGraphHealthSnapshot, FlowGraphHealthStatus, FlowGraphObserver, MemoryFlowDecisionLedger,
167    FLOW_GRAPH_SOURCE,
168};
169pub use llm::{
170    clear_http_metrics_callback, set_http_metrics_callback, AnthropicClient, Attachment,
171    ContentBlock, HttpMetricsCallback, HttpMetricsRecord, ImageSource, LlmClient, LlmResponse,
172    Message, ModelGenerationAdmission, ModelGenerationAdmissionError, ModelGenerationConcurrency,
173    ModelGenerationPermit, OpenAiClient, TokenUsage,
174};
175pub use orchestration::{
176    execute_loop, execute_pipeline, execute_steps_parallel, execute_steps_parallel_resumable,
177    AgentExecutor, AgentStepSpec, BudgetSnapshot, LoopDecision, PipelineStage, StepOutcome,
178    Workflow, WorkflowBudget, WorkflowBuilder, WorkflowCheckpoint, WorkflowEvent,
179    WorkflowStepRecord, WORKFLOW_CHECKPOINT_SCHEMA_VERSION,
180};
181pub use prompts::{AgentStyle, DetectionConfidence, PlanningMode, SystemPromptSlots};
182pub use rl_trajectory::{RlTrajectoryConfig, RlTrajectoryMode, RlTrajectoryRecorder};
183pub use run::{
184    ActiveToolSnapshot, InMemoryRunStore, RunEventRecord, RunHandle, RunRecord, RunSnapshot,
185    RunStatus,
186};
187pub use state_graph::{
188    graph_event_head, Behavior, BehaviorContext, BehaviorError, EventFilter, ExternalEvent,
189    ExternalProjectionOutcome, FileGraphEventStore, FnBehavior, GraphDiff, GraphEvent,
190    GraphEventRecord, GraphEventStore, GraphObject, GraphPatch, GraphRelation, GraphRuntime,
191    GraphSaveOutcome, MemoryGraphEventStore, ObjectId, PatchOperation, RelationId, ReplayError,
192    RuntimeError as GraphRuntimeError, RuntimeLimits, StateGraph, GRAPH_EVENT_SCHEMA_VERSION,
193};
194pub use subagent::{
195    AgentDefinition, AgentRegistry, CattleAgentKind, CattleAgentSpec, ConfirmationInheritance,
196    WorkerAgentKind, WorkerAgentSpec,
197};
198pub use subagent_task_tracker::{
199    InMemorySubagentTaskTracker, SubagentProgressEntry, SubagentStatus, SubagentTaskSnapshot,
200};
201pub use tools::{ToolCapabilities, ToolErrorKind, ToolOutputKind};
202pub use workspace::{
203    CommandOutput, CommandOutputObserver, CommandOutputSummary, CommandRequest,
204    LocalWorkspaceAccessPolicy, LocalWorkspaceBackend, LocalWorkspaceFile,
205    LocalWorkspaceFileStatus, LocalWorkspaceManifest, LocalWorkspaceManifestSnapshot,
206    ManifestWorkspaceBackend, RecentWorkspaceFile, RemoteGitBackend, RemoteGitBackendConfig,
207    RemoteGitConflict, VirtualPathResolver, WorkspaceCapabilities, WorkspaceCommandRunner,
208    WorkspaceDirEntry, WorkspaceError, WorkspaceFileChange, WorkspaceFileChangeKind,
209    WorkspaceFileSystem, WorkspaceFileSystemExt, WorkspaceFileType, WorkspaceGit,
210    WorkspaceGitBranch, WorkspaceGitCheckoutOutput, WorkspaceGitCheckoutRequest,
211    WorkspaceGitCommit, WorkspaceGitCreateBranchRequest, WorkspaceGitCreateWorktreeRequest,
212    WorkspaceGitDiffRequest, WorkspaceGitRemote, WorkspaceGitRemoveWorktreeRequest,
213    WorkspaceGitStash, WorkspaceGitStashProvider, WorkspaceGitStashRequest, WorkspaceGitStatus,
214    WorkspaceGitWorktree, WorkspaceGitWorktreeMutation, WorkspaceGitWorktreeProvider,
215    WorkspaceGlobRequest, WorkspaceGlobResult, WorkspaceGrepOutcome, WorkspaceGrepRequest,
216    WorkspaceGrepResult, WorkspacePath, WorkspacePathResolver, WorkspaceRef, WorkspaceResult,
217    WorkspaceSearch, WorkspaceServices, WorkspaceServicesBuilder, WorkspaceTextRange,
218    WorkspaceTextReader, WorkspaceVersionConflict, WorkspaceWriteOutcome,
219};
220#[cfg(feature = "s3")]
221pub use workspace::{S3BackendConfig, S3WorkspaceBackend};
a3s_code_core/lib.rs

a3s_code_core/
lib.rs
