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("/my-project", None)?;
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(
52//!     "/my-project",
53//!     Some(SessionOptions::new().with_worker_agent(frontend)),
54//! )?;
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;
79#[cfg(feature = "ahp")]
80pub mod ahp;
81pub mod budget;
82pub(crate) mod child_run;
83pub mod commands;
84pub(crate) mod compaction;
85pub mod config;
86pub mod context;
87pub mod dynamic_workflow;
88pub mod error;
89pub(crate) mod file_history;
90pub(crate) mod git;
91pub mod hitl;
92pub mod hooks;
93pub mod host_env;
94pub mod llm;
95pub mod loop_checkpoint;
96pub mod mcp;
97pub mod memory;
98pub mod orchestration;
99pub(crate) mod ordered_parallel;
100pub mod permissions;
101pub mod planning;
102pub mod program;
103pub(crate) mod prompts;
104pub mod queue;
105pub mod retention;
106pub(crate) mod retry;
107pub mod rl_trajectory;
108pub mod run;
109pub(crate) mod safety_gate;
110pub mod sandbox;
111pub mod security;
112#[cfg(feature = "serve")]
113pub mod serve;
114pub(crate) mod session_lane_queue;
115pub mod skills;
116pub(crate) mod sse;
117pub mod store;
118pub mod subagent;
119pub mod subagent_task_tracker;
120pub mod telemetry;
121#[cfg(feature = "telemetry")]
122pub mod telemetry_otel;
123pub(crate) mod text;
124pub(crate) mod tool_confirmation;
125pub mod tools;
126pub mod trace;
127pub mod verification;
128pub mod workspace;
129
130// Re-export key types at crate root for ergonomic usage
131pub use agent::{AgentEvent, AgentResult};
132pub use agent_api::{Agent, AgentSession, ReadFileOptions, SessionOptions, ToolCallResult};
133pub use config::{
134    AutoDelegationConfig, CodeConfig, ModelConfig, ModelCost, ModelLimit, ModelModalities,
135    OsConfig, ProviderConfig,
136};
137pub use dynamic_workflow::{
138    DynamicWorkflowRuntime, DynamicWorkflowScriptLimits, DynamicWorkflowTool,
139};
140pub use error::{CodeError, Result};
141pub use llm::{
142    clear_http_metrics_callback, set_http_metrics_callback, AnthropicClient, Attachment,
143    ContentBlock, HttpMetricsCallback, HttpMetricsRecord, ImageSource, LlmClient, LlmResponse,
144    Message, OpenAiClient, TokenUsage,
145};
146pub use orchestration::{
147    execute_loop, execute_pipeline, execute_steps_parallel, execute_steps_parallel_resumable,
148    AgentExecutor, AgentStepSpec, BudgetSnapshot, LoopDecision, PipelineStage, StepOutcome,
149    Workflow, WorkflowBudget, WorkflowBuilder, WorkflowCheckpoint, WorkflowEvent,
150    WorkflowStepRecord, WORKFLOW_CHECKPOINT_SCHEMA_VERSION,
151};
152pub use prompts::{AgentStyle, DetectionConfidence, PlanningMode, SystemPromptSlots};
153pub use rl_trajectory::{RlTrajectoryConfig, RlTrajectoryMode, RlTrajectoryRecorder};
154pub use run::{
155    ActiveToolSnapshot, InMemoryRunStore, RunEventRecord, RunHandle, RunRecord, RunSnapshot,
156    RunStatus,
157};
158pub use subagent::{
159    AgentDefinition, AgentRegistry, CattleAgentKind, CattleAgentSpec, ConfirmationInheritance,
160    WorkerAgentKind, WorkerAgentSpec,
161};
162pub use subagent_task_tracker::{
163    InMemorySubagentTaskTracker, SubagentProgressEntry, SubagentStatus, SubagentTaskSnapshot,
164};
165pub use tools::ToolErrorKind;
166pub use workspace::{
167    CommandOutput, CommandOutputObserver, CommandRequest, LocalWorkspaceBackend,
168    LocalWorkspaceFile, LocalWorkspaceFileStatus, LocalWorkspaceManifest,
169    LocalWorkspaceManifestSnapshot, ManifestWorkspaceBackend, RecentWorkspaceFile,
170    RemoteGitBackend, RemoteGitBackendConfig, RemoteGitConflict, VirtualPathResolver,
171    WorkspaceCapabilities, WorkspaceCommandRunner, WorkspaceDirEntry, WorkspaceError,
172    WorkspaceFileSystem, WorkspaceFileSystemExt, WorkspaceFileType, WorkspaceGit,
173    WorkspaceGitBranch, WorkspaceGitCheckoutOutput, WorkspaceGitCheckoutRequest,
174    WorkspaceGitCommit, WorkspaceGitCreateBranchRequest, WorkspaceGitCreateWorktreeRequest,
175    WorkspaceGitDiffRequest, WorkspaceGitRemote, WorkspaceGitRemoveWorktreeRequest,
176    WorkspaceGitStash, WorkspaceGitStashProvider, WorkspaceGitStashRequest, WorkspaceGitStatus,
177    WorkspaceGitWorktree, WorkspaceGitWorktreeMutation, WorkspaceGitWorktreeProvider,
178    WorkspaceGlobRequest, WorkspaceGlobResult, WorkspaceGrepRequest, WorkspaceGrepResult,
179    WorkspacePath, WorkspacePathResolver, WorkspaceRef, WorkspaceResult, WorkspaceSearch,
180    WorkspaceServices, WorkspaceServicesBuilder, WorkspaceVersionConflict, WorkspaceWriteOutcome,
181};
182#[cfg(feature = "s3")]
183pub use workspace::{S3BackendConfig, S3WorkspaceBackend};
a3s_code_core/lib.rs

a3s_code_core/
lib.rs
