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 mod store;
117pub mod subagent;
118pub mod subagent_task_tracker;
119pub mod telemetry;
120#[cfg(feature = "telemetry")]
121pub mod telemetry_otel;
122pub(crate) mod text;
123pub(crate) mod tool_confirmation;
124pub mod tools;
125pub mod trace;
126pub mod verification;
127pub mod workspace;
128
129// Re-export key types at crate root for ergonomic usage
130pub use agent::{AgentEvent, AgentResult};
131pub use agent_api::{Agent, AgentSession, SessionOptions, ToolCallResult};
132pub use config::{
133    AutoDelegationConfig, CodeConfig, ModelConfig, ModelCost, ModelLimit, ModelModalities,
134    OsConfig, ProviderConfig,
135};
136pub use dynamic_workflow::{
137    DynamicWorkflowRuntime, DynamicWorkflowScriptLimits, DynamicWorkflowTool,
138};
139pub use error::{CodeError, Result};
140pub use llm::{
141    clear_http_metrics_callback, set_http_metrics_callback, AnthropicClient, Attachment,
142    ContentBlock, HttpMetricsCallback, HttpMetricsRecord, ImageSource, LlmClient, LlmResponse,
143    Message, OpenAiClient, TokenUsage,
144};
145pub use orchestration::{
146    execute_loop, execute_pipeline, execute_steps_parallel, execute_steps_parallel_resumable,
147    AgentExecutor, AgentStepSpec, BudgetSnapshot, LoopDecision, PipelineStage, StepOutcome,
148    Workflow, WorkflowBudget, WorkflowBuilder, WorkflowCheckpoint, WorkflowEvent,
149    WorkflowStepRecord, WORKFLOW_CHECKPOINT_SCHEMA_VERSION,
150};
151pub use prompts::{AgentStyle, DetectionConfidence, PlanningMode, SystemPromptSlots};
152pub use rl_trajectory::{RlTrajectoryConfig, RlTrajectoryMode, RlTrajectoryRecorder};
153pub use run::{
154    ActiveToolSnapshot, InMemoryRunStore, RunEventRecord, RunHandle, RunRecord, RunSnapshot,
155    RunStatus,
156};
157pub use subagent::{
158    AgentDefinition, AgentRegistry, CattleAgentKind, CattleAgentSpec, ConfirmationInheritance,
159    WorkerAgentKind, WorkerAgentSpec,
160};
161pub use subagent_task_tracker::{
162    InMemorySubagentTaskTracker, SubagentProgressEntry, SubagentStatus, SubagentTaskSnapshot,
163};
164pub use tools::ToolErrorKind;
165pub use workspace::{
166    CommandOutput, CommandOutputObserver, CommandRequest, LocalWorkspaceBackend,
167    LocalWorkspaceFile, LocalWorkspaceFileStatus, LocalWorkspaceManifest,
168    LocalWorkspaceManifestSnapshot, ManifestWorkspaceBackend, RecentWorkspaceFile,
169    RemoteGitBackend, RemoteGitBackendConfig, RemoteGitConflict, VirtualPathResolver,
170    WorkspaceCapabilities, WorkspaceCommandRunner, WorkspaceDirEntry, WorkspaceError,
171    WorkspaceFileSystem, WorkspaceFileSystemExt, WorkspaceFileType, WorkspaceGit,
172    WorkspaceGitBranch, WorkspaceGitCheckoutOutput, WorkspaceGitCheckoutRequest,
173    WorkspaceGitCommit, WorkspaceGitCreateBranchRequest, WorkspaceGitCreateWorktreeRequest,
174    WorkspaceGitDiffRequest, WorkspaceGitRemote, WorkspaceGitRemoveWorktreeRequest,
175    WorkspaceGitStash, WorkspaceGitStashProvider, WorkspaceGitStashRequest, WorkspaceGitStatus,
176    WorkspaceGitWorktree, WorkspaceGitWorktreeMutation, WorkspaceGitWorktreeProvider,
177    WorkspaceGlobRequest, WorkspaceGlobResult, WorkspaceGrepRequest, WorkspaceGrepResult,
178    WorkspacePath, WorkspacePathResolver, WorkspaceRef, WorkspaceResult, WorkspaceSearch,
179    WorkspaceServices, WorkspaceServicesBuilder, WorkspaceVersionConflict, WorkspaceWriteOutcome,
180};
181#[cfg(feature = "s3")]
182pub use workspace::{S3BackendConfig, S3WorkspaceBackend};
a3s_code_core/lib.rs

a3s_code_core/
lib.rs
