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

a3s_code_core/
lib.rs
