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;
113pub mod search_runtime;
114pub mod security;
115#[cfg(feature = "serve")]
116pub mod serve;
117pub(crate) mod session_lane_queue;
118pub mod skills;
119pub(crate) mod sse;
120pub mod state_graph;
121pub mod store;
122pub mod subagent;
123pub mod subagent_task_tracker;
124pub mod telemetry;
125#[cfg(feature = "telemetry")]
126pub mod telemetry_otel;
127pub(crate) mod text;
128pub(crate) mod tool_confirmation;
129pub mod tools;
130pub mod trace;
131pub mod verification;
132pub mod workspace;
133
134// Re-export key types at crate root for ergonomic usage
135pub use agent::{AgentEvent, AgentResult};
136pub use agent_api::{
137    Agent, AgentSession, ReadFileOptions, SessionBuilder, SessionOptions, ToolCallResult,
138};
139pub use code_intelligence::{
140    CodeDiagnostic, CodeDiagnosticSeverity, CodeIntelligenceCapabilities, CodeIntelligenceError,
141    CodeIntelligenceLanguageStatus, CodeIntelligenceResult, CodeIntelligenceState,
142    CodeIntelligenceStatus, CodeLocation, CodePosition, CodeQueryResult, CodeRange, CodeSymbolKind,
143    DocumentRevision, DocumentSnapshot, DocumentSymbol, LanguageId, LocalCodeIntelligence,
144    NavigationKind, SymbolInformation, WorkspaceCodeIntelligence,
145};
146pub use config::{
147    AutoDelegationConfig, CodeConfig, ModelConfig, ModelCost, ModelLimit, ModelModalities,
148    OsConfig, ProviderConfig,
149};
150pub use dynamic_workflow::{
151    dynamic_workflow_store_path, DynamicWorkflowRuntime, DynamicWorkflowScriptLimits,
152    DynamicWorkflowTool, DYNAMIC_WORKFLOW_STORE_RELATIVE_PATH,
153};
154pub use error::SessionBuildResource;
155pub use error::{CodeError, Result};
156pub use event_protocol::{
157    run_event_envelope_v1, AgentEventProjectionV1, AgentEventTypeV1, EventEnvelopeV1,
158    EventProtocolError, AGENT_EVENT_TYPES_V1, EVENT_ENVELOPE_V1_VERSION,
159};
160pub use flow_graph::{
161    run_object_id as flow_run_object_id, step_object_id as flow_step_object_id,
162    FileFlowDecisionLedger, FlowDecision, FlowDecisionClaimOutcome, FlowDecisionDispatchError,
163    FlowDecisionDispatcher, FlowDecisionHealthSnapshot, FlowDecisionHealthStatus,
164    FlowDecisionLedger, FlowDecisionRequest, FlowDecisionSink, FlowDecisionStep,
165    FlowGraphHealthSnapshot, FlowGraphHealthStatus, FlowGraphObserver, MemoryFlowDecisionLedger,
166    FLOW_GRAPH_SOURCE,
167};
168pub use llm::{
169    clear_http_metrics_callback, set_http_metrics_callback, AnthropicClient, Attachment,
170    ContentBlock, HttpMetricsCallback, HttpMetricsRecord, ImageSource, LlmClient, LlmResponse,
171    Message, OpenAiClient, TokenUsage,
172};
173pub use orchestration::{
174    execute_loop, execute_pipeline, execute_steps_parallel, execute_steps_parallel_resumable,
175    AgentExecutor, AgentStepSpec, BudgetSnapshot, LoopDecision, PipelineStage, StepOutcome,
176    Workflow, WorkflowBudget, WorkflowBuilder, WorkflowCheckpoint, WorkflowEvent,
177    WorkflowStepRecord, WORKFLOW_CHECKPOINT_SCHEMA_VERSION,
178};
179pub use prompts::{AgentStyle, DetectionConfidence, PlanningMode, SystemPromptSlots};
180pub use rl_trajectory::{RlTrajectoryConfig, RlTrajectoryMode, RlTrajectoryRecorder};
181pub use run::{
182    ActiveToolSnapshot, InMemoryRunStore, RunEventRecord, RunHandle, RunRecord, RunSnapshot,
183    RunStatus,
184};
185pub use state_graph::{
186    graph_event_head, Behavior, BehaviorContext, BehaviorError, EventFilter, ExternalEvent,
187    ExternalProjectionOutcome, FileGraphEventStore, FnBehavior, GraphDiff, GraphEvent,
188    GraphEventRecord, GraphEventStore, GraphObject, GraphPatch, GraphRelation, GraphRuntime,
189    GraphSaveOutcome, MemoryGraphEventStore, ObjectId, PatchOperation, RelationId, ReplayError,
190    RuntimeError as GraphRuntimeError, RuntimeLimits, StateGraph, GRAPH_EVENT_SCHEMA_VERSION,
191};
192pub use subagent::{
193    AgentDefinition, AgentRegistry, CattleAgentKind, CattleAgentSpec, ConfirmationInheritance,
194    WorkerAgentKind, WorkerAgentSpec,
195};
196pub use subagent_task_tracker::{
197    InMemorySubagentTaskTracker, SubagentProgressEntry, SubagentStatus, SubagentTaskSnapshot,
198};
199pub use tools::{ToolCapabilities, ToolErrorKind, ToolOutputKind};
200pub use workspace::{
201    CommandOutput, CommandOutputObserver, CommandOutputSummary, CommandRequest,
202    LocalWorkspaceBackend, LocalWorkspaceFile, LocalWorkspaceFileStatus, LocalWorkspaceManifest,
203    LocalWorkspaceManifestSnapshot, ManifestWorkspaceBackend, RecentWorkspaceFile,
204    RemoteGitBackend, RemoteGitBackendConfig, RemoteGitConflict, VirtualPathResolver,
205    WorkspaceCapabilities, WorkspaceCommandRunner, WorkspaceDirEntry, WorkspaceError,
206    WorkspaceFileChange, WorkspaceFileChangeKind, WorkspaceFileSystem, WorkspaceFileSystemExt,
207    WorkspaceFileType, WorkspaceGit, WorkspaceGitBranch, WorkspaceGitCheckoutOutput,
208    WorkspaceGitCheckoutRequest, WorkspaceGitCommit, WorkspaceGitCreateBranchRequest,
209    WorkspaceGitCreateWorktreeRequest, WorkspaceGitDiffRequest, WorkspaceGitRemote,
210    WorkspaceGitRemoveWorktreeRequest, WorkspaceGitStash, WorkspaceGitStashProvider,
211    WorkspaceGitStashRequest, WorkspaceGitStatus, WorkspaceGitWorktree,
212    WorkspaceGitWorktreeMutation, WorkspaceGitWorktreeProvider, WorkspaceGlobRequest,
213    WorkspaceGlobResult, WorkspaceGrepOutcome, WorkspaceGrepRequest, WorkspaceGrepResult,
214    WorkspacePath, WorkspacePathResolver, WorkspaceRef, WorkspaceResult, WorkspaceSearch,
215    WorkspaceServices, WorkspaceServicesBuilder, WorkspaceTextRange, WorkspaceTextReader,
216    WorkspaceVersionConflict, WorkspaceWriteOutcome,
217};
218#[cfg(feature = "s3")]
219pub use workspace::{S3BackendConfig, S3WorkspaceBackend};
a3s_code_core/lib.rs

a3s_code_core/
lib.rs
