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

a3s_code_core/
lib.rs
