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_async("/my-project", None).await?;
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_async(
52//!     "/my-project",
53//!     Some(SessionOptions::new().with_worker_agent(frontend)),
54//! ).await?;
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;
79pub mod budget;
80pub(crate) mod child_run;
81pub mod commands;
82pub(crate) mod compaction;
83pub mod config;
84pub mod context;
85pub mod dynamic_workflow;
86pub mod error;
87pub mod event_protocol;
88pub(crate) mod git;
89pub mod hitl;
90pub mod hooks;
91pub mod host_env;
92pub mod llm;
93pub mod loop_checkpoint;
94pub mod mcp;
95pub mod memory;
96pub mod orchestration;
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 rl_trajectory;
106pub mod run;
107pub(crate) mod safety_gate;
108pub mod sandbox;
109pub mod security;
110#[cfg(feature = "serve")]
111pub mod serve;
112pub(crate) mod session_lane_queue;
113pub mod skills;
114pub(crate) mod sse;
115pub mod state_graph;
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::{
132    Agent, AgentSession, ReadFileOptions, SessionBuilder, SessionOptions, ToolCallResult,
133};
134pub use config::{
135    AutoDelegationConfig, CodeConfig, ModelConfig, ModelCost, ModelLimit, ModelModalities,
136    OsConfig, ProviderConfig,
137};
138pub use dynamic_workflow::{
139    dynamic_workflow_store_path, DynamicWorkflowRuntime, DynamicWorkflowScriptLimits,
140    DynamicWorkflowTool, DYNAMIC_WORKFLOW_STORE_RELATIVE_PATH,
141};
142pub use error::SessionBuildResource;
143pub use error::{CodeError, Result};
144pub use event_protocol::{
145    run_event_envelope_v1, AgentEventProjectionV1, AgentEventTypeV1, EventEnvelopeV1,
146    EventProtocolError, AGENT_EVENT_TYPES_V1, EVENT_ENVELOPE_V1_VERSION,
147};
148pub use llm::{
149    clear_http_metrics_callback, set_http_metrics_callback, AnthropicClient, Attachment,
150    ContentBlock, HttpMetricsCallback, HttpMetricsRecord, ImageSource, LlmClient, LlmResponse,
151    Message, OpenAiClient, TokenUsage,
152};
153pub use orchestration::{
154    execute_loop, execute_pipeline, execute_steps_parallel, execute_steps_parallel_resumable,
155    AgentExecutor, AgentStepSpec, BudgetSnapshot, LoopDecision, PipelineStage, StepOutcome,
156    Workflow, WorkflowBudget, WorkflowBuilder, WorkflowCheckpoint, WorkflowEvent,
157    WorkflowStepRecord, WORKFLOW_CHECKPOINT_SCHEMA_VERSION,
158};
159pub use prompts::{AgentStyle, DetectionConfidence, PlanningMode, SystemPromptSlots};
160pub use rl_trajectory::{RlTrajectoryConfig, RlTrajectoryMode, RlTrajectoryRecorder};
161pub use run::{
162    ActiveToolSnapshot, InMemoryRunStore, RunEventRecord, RunHandle, RunRecord, RunSnapshot,
163    RunStatus,
164};
165pub use state_graph::{
166    Behavior, BehaviorContext, BehaviorError, EventFilter, FileGraphEventStore, FnBehavior,
167    GraphDiff, GraphEvent, GraphEventRecord, GraphEventStore, GraphObject, GraphPatch,
168    GraphRelation, GraphRuntime, MemoryGraphEventStore, ObjectId, PatchOperation, RelationId,
169    ReplayError, RuntimeError as GraphRuntimeError, RuntimeLimits, StateGraph,
170    GRAPH_EVENT_SCHEMA_VERSION,
171};
172pub use subagent::{
173    AgentDefinition, AgentRegistry, CattleAgentKind, CattleAgentSpec, ConfirmationInheritance,
174    WorkerAgentKind, WorkerAgentSpec,
175};
176pub use subagent_task_tracker::{
177    InMemorySubagentTaskTracker, SubagentProgressEntry, SubagentStatus, SubagentTaskSnapshot,
178};
179pub use tools::ToolErrorKind;
180pub use workspace::{
181    CommandOutput, CommandOutputObserver, CommandRequest, LocalWorkspaceBackend,
182    LocalWorkspaceFile, LocalWorkspaceFileStatus, LocalWorkspaceManifest,
183    LocalWorkspaceManifestSnapshot, ManifestWorkspaceBackend, RecentWorkspaceFile,
184    RemoteGitBackend, RemoteGitBackendConfig, RemoteGitConflict, VirtualPathResolver,
185    WorkspaceCapabilities, WorkspaceCommandRunner, WorkspaceDirEntry, WorkspaceError,
186    WorkspaceFileSystem, WorkspaceFileSystemExt, WorkspaceFileType, WorkspaceGit,
187    WorkspaceGitBranch, WorkspaceGitCheckoutOutput, WorkspaceGitCheckoutRequest,
188    WorkspaceGitCommit, WorkspaceGitCreateBranchRequest, WorkspaceGitCreateWorktreeRequest,
189    WorkspaceGitDiffRequest, WorkspaceGitRemote, WorkspaceGitRemoveWorktreeRequest,
190    WorkspaceGitStash, WorkspaceGitStashProvider, WorkspaceGitStashRequest, WorkspaceGitStatus,
191    WorkspaceGitWorktree, WorkspaceGitWorktreeMutation, WorkspaceGitWorktreeProvider,
192    WorkspaceGlobRequest, WorkspaceGlobResult, WorkspaceGrepOutcome, WorkspaceGrepRequest,
193    WorkspaceGrepResult, WorkspacePath, WorkspacePathResolver, WorkspaceRef, WorkspaceResult,
194    WorkspaceSearch, WorkspaceServices, WorkspaceServicesBuilder, WorkspaceVersionConflict,
195    WorkspaceWriteOutcome,
196};
197#[cfg(feature = "s3")]
198pub use workspace::{S3BackendConfig, S3WorkspaceBackend};
a3s_code_core/lib.rs

a3s_code_core/
lib.rs
