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(crate) mod child_run;
82pub mod commands;
83pub(crate) mod compaction;
84pub mod config;
85pub mod context;
86pub mod error;
87pub(crate) mod file_history;
88pub(crate) mod git;
89pub mod hitl;
90pub mod hooks;
91pub mod llm;
92pub mod mcp;
93pub mod memory;
94pub mod permissions;
95pub mod planning;
96pub mod program;
97pub(crate) mod prompts;
98pub mod queue;
99pub(crate) mod retry;
100pub mod run;
101pub(crate) mod safety_gate;
102pub mod sandbox;
103pub mod security;
104pub(crate) mod session_lane_queue;
105pub mod skills;
106pub mod store;
107pub mod subagent;
108pub mod telemetry;
109#[cfg(feature = "telemetry")]
110pub mod telemetry_otel;
111pub(crate) mod text;
112pub(crate) mod tool_confirmation;
113pub mod tools;
114pub mod trace;
115pub mod verification;
116pub mod workspace;
117
118// Re-export key types at crate root for ergonomic usage
119pub use agent::{AgentEvent, AgentResult};
120pub use agent_api::{Agent, AgentSession, SessionOptions, ToolCallResult};
121pub use config::{CodeConfig, ModelConfig, ModelCost, ModelLimit, ModelModalities, ProviderConfig};
122pub use error::{CodeError, Result};
123pub use llm::{
124    clear_http_metrics_callback, set_http_metrics_callback, AnthropicClient, Attachment,
125    ContentBlock, HttpMetricsCallback, HttpMetricsRecord, ImageSource, LlmClient, LlmResponse,
126    Message, OpenAiClient, TokenUsage,
127};
128pub use prompts::{AgentStyle, DetectionConfidence, PlanningMode, SystemPromptSlots};
129pub use run::{
130    ActiveToolSnapshot, InMemoryRunStore, RunEventRecord, RunHandle, RunRecord, RunSnapshot,
131    RunStatus,
132};
133pub use subagent::{
134    AgentDefinition, AgentRegistry, CattleAgentKind, CattleAgentSpec, ConfirmationInheritance,
135    WorkerAgentKind, WorkerAgentSpec,
136};
137pub use workspace::{
138    CommandOutput, CommandOutputObserver, CommandRequest, LocalWorkspaceBackend,
139    VirtualPathResolver, WorkspaceCapabilities, WorkspaceCommandRunner, WorkspaceDirEntry,
140    WorkspaceFileSystem, WorkspaceFileType, WorkspaceGit, WorkspaceGitBranch,
141    WorkspaceGitCheckoutOutput, WorkspaceGitCheckoutRequest, WorkspaceGitCommit,
142    WorkspaceGitCreateBranchRequest, WorkspaceGitCreateWorktreeRequest, WorkspaceGitDiffRequest,
143    WorkspaceGitRemote, WorkspaceGitRemoveWorktreeRequest, WorkspaceGitStash,
144    WorkspaceGitStashProvider, WorkspaceGitStashRequest, WorkspaceGitStatus, WorkspaceGitWorktree,
145    WorkspaceGitWorktreeMutation, WorkspaceGitWorktreeProvider, WorkspaceGlobRequest,
146    WorkspaceGlobResult, WorkspaceGrepRequest, WorkspaceGrepResult, WorkspacePath,
147    WorkspacePathResolver, WorkspaceRef, WorkspaceSearch, WorkspaceServices,
148    WorkspaceServicesBuilder, WorkspaceWriteOutcome,
149};
150#[cfg(feature = "s3")]
151pub use workspace::{S3BackendConfig, S3WorkspaceBackend};
a3s_code_core/lib.rs

a3s_code_core/
lib.rs
