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_pipeline, execute_steps_parallel, execute_steps_parallel_resumable, AgentExecutor,
140    AgentStepSpec, PipelineStage, StepOutcome, WorkflowCheckpoint, WorkflowStepRecord,
141    WORKFLOW_CHECKPOINT_SCHEMA_VERSION,
142};
143pub use prompts::{AgentStyle, DetectionConfidence, PlanningMode, SystemPromptSlots};
144pub use run::{
145    ActiveToolSnapshot, InMemoryRunStore, RunEventRecord, RunHandle, RunRecord, RunSnapshot,
146    RunStatus,
147};
148pub use subagent::{
149    AgentDefinition, AgentRegistry, CattleAgentKind, CattleAgentSpec, ConfirmationInheritance,
150    WorkerAgentKind, WorkerAgentSpec,
151};
152pub use subagent_task_tracker::{
153    InMemorySubagentTaskTracker, SubagentProgressEntry, SubagentStatus, SubagentTaskSnapshot,
154};
155pub use tools::ToolErrorKind;
156pub use workspace::{
157    CommandOutput, CommandOutputObserver, CommandRequest, LocalWorkspaceBackend, RemoteGitBackend,
158    RemoteGitBackendConfig, RemoteGitConflict, VirtualPathResolver, WorkspaceCapabilities,
159    WorkspaceCommandRunner, WorkspaceDirEntry, WorkspaceError, WorkspaceFileSystem,
160    WorkspaceFileSystemExt, WorkspaceFileType, WorkspaceGit, WorkspaceGitBranch,
161    WorkspaceGitCheckoutOutput, WorkspaceGitCheckoutRequest, WorkspaceGitCommit,
162    WorkspaceGitCreateBranchRequest, WorkspaceGitCreateWorktreeRequest, WorkspaceGitDiffRequest,
163    WorkspaceGitRemote, WorkspaceGitRemoveWorktreeRequest, WorkspaceGitStash,
164    WorkspaceGitStashProvider, WorkspaceGitStashRequest, WorkspaceGitStatus, WorkspaceGitWorktree,
165    WorkspaceGitWorktreeMutation, WorkspaceGitWorktreeProvider, WorkspaceGlobRequest,
166    WorkspaceGlobResult, WorkspaceGrepRequest, WorkspaceGrepResult, WorkspacePath,
167    WorkspacePathResolver, WorkspaceRef, WorkspaceResult, WorkspaceSearch, WorkspaceServices,
168    WorkspaceServicesBuilder, WorkspaceVersionConflict, WorkspaceWriteOutcome,
169};
170#[cfg(feature = "s3")]
171pub use workspace::{S3BackendConfig, S3WorkspaceBackend};
a3s_code_core/lib.rs

a3s_code_core/
lib.rs
