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

a3s_code_core/
lib.rs
