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 mod flow_graph;
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 rl_trajectory;
107pub mod run;
108pub(crate) mod safety_gate;
109pub mod sandbox;
110pub mod search_runtime;
111pub mod security;
112#[cfg(feature = "serve")]
113pub mod serve;
114pub(crate) mod session_lane_queue;
115pub mod skills;
116pub(crate) mod sse;
117pub mod state_graph;
118pub mod store;
119pub mod subagent;
120pub mod subagent_task_tracker;
121pub mod telemetry;
122#[cfg(feature = "telemetry")]
123pub mod telemetry_otel;
124pub(crate) mod text;
125pub(crate) mod token_estimate;
126pub(crate) mod tool_confirmation;
127pub mod tools;
128pub mod trace;
129pub mod verification;
130pub mod workspace;
131
132// Re-export key types at crate root for ergonomic usage
133pub use agent::{AgentEvent, AgentResult};
134pub use agent_api::{
135    Agent, AgentSession, ReadFileOptions, SessionBuilder, SessionOptions, ToolCallResult,
136};
137pub use config::{
138    AutoDelegationConfig, CodeConfig, ModelConfig, ModelCost, ModelLimit, ModelModalities,
139    OsConfig, ProviderConfig,
140};
141pub use dynamic_workflow::{
142    dynamic_workflow_store_path, DynamicWorkflowRuntime, DynamicWorkflowScriptLimits,
143    DynamicWorkflowTool, DYNAMIC_WORKFLOW_STORE_RELATIVE_PATH,
144};
145pub use error::SessionBuildResource;
146pub use error::{CodeError, Result};
147pub use event_protocol::{
148    run_event_envelope_v1, AgentEventProjectionV1, AgentEventTypeV1, EventEnvelopeV1,
149    EventProtocolError, AGENT_EVENT_TYPES_V1, EVENT_ENVELOPE_V1_VERSION,
150};
151pub use flow_graph::{
152    run_object_id as flow_run_object_id, step_object_id as flow_step_object_id,
153    FileFlowDecisionLedger, FlowDecision, FlowDecisionClaimOutcome, FlowDecisionDispatchError,
154    FlowDecisionDispatcher, FlowDecisionHealthSnapshot, FlowDecisionHealthStatus,
155    FlowDecisionLedger, FlowDecisionRequest, FlowDecisionSink, FlowDecisionStep,
156    FlowGraphHealthSnapshot, FlowGraphHealthStatus, FlowGraphObserver, MemoryFlowDecisionLedger,
157    FLOW_GRAPH_SOURCE,
158};
159pub use llm::{
160    clear_http_metrics_callback, set_http_metrics_callback, AnthropicClient, Attachment,
161    ContentBlock, HttpMetricsCallback, HttpMetricsRecord, ImageSource, LlmClient, LlmResponse,
162    Message, OpenAiClient, TokenUsage,
163};
164pub use orchestration::{
165    execute_loop, execute_pipeline, execute_steps_parallel, execute_steps_parallel_resumable,
166    AgentExecutor, AgentStepSpec, BudgetSnapshot, LoopDecision, PipelineStage, StepOutcome,
167    Workflow, WorkflowBudget, WorkflowBuilder, WorkflowCheckpoint, WorkflowEvent,
168    WorkflowStepRecord, WORKFLOW_CHECKPOINT_SCHEMA_VERSION,
169};
170pub use prompts::{AgentStyle, DetectionConfidence, PlanningMode, SystemPromptSlots};
171pub use rl_trajectory::{RlTrajectoryConfig, RlTrajectoryMode, RlTrajectoryRecorder};
172pub use run::{
173    ActiveToolSnapshot, InMemoryRunStore, RunEventRecord, RunHandle, RunRecord, RunSnapshot,
174    RunStatus,
175};
176pub use state_graph::{
177    graph_event_head, Behavior, BehaviorContext, BehaviorError, EventFilter, ExternalEvent,
178    ExternalProjectionOutcome, FileGraphEventStore, FnBehavior, GraphDiff, GraphEvent,
179    GraphEventRecord, GraphEventStore, GraphObject, GraphPatch, GraphRelation, GraphRuntime,
180    GraphSaveOutcome, MemoryGraphEventStore, ObjectId, PatchOperation, RelationId, ReplayError,
181    RuntimeError as GraphRuntimeError, RuntimeLimits, StateGraph, GRAPH_EVENT_SCHEMA_VERSION,
182};
183pub use subagent::{
184    AgentDefinition, AgentRegistry, CattleAgentKind, CattleAgentSpec, ConfirmationInheritance,
185    WorkerAgentKind, WorkerAgentSpec,
186};
187pub use subagent_task_tracker::{
188    InMemorySubagentTaskTracker, SubagentProgressEntry, SubagentStatus, SubagentTaskSnapshot,
189};
190pub use tools::{ToolCapabilities, ToolErrorKind, ToolOutputKind};
191pub use workspace::{
192    CommandOutput, CommandOutputObserver, CommandOutputSummary, CommandRequest,
193    LocalWorkspaceBackend, LocalWorkspaceFile, LocalWorkspaceFileStatus, LocalWorkspaceManifest,
194    LocalWorkspaceManifestSnapshot, ManifestWorkspaceBackend, RecentWorkspaceFile,
195    RemoteGitBackend, RemoteGitBackendConfig, RemoteGitConflict, VirtualPathResolver,
196    WorkspaceCapabilities, WorkspaceCommandRunner, WorkspaceDirEntry, WorkspaceError,
197    WorkspaceFileSystem, WorkspaceFileSystemExt, WorkspaceFileType, WorkspaceGit,
198    WorkspaceGitBranch, WorkspaceGitCheckoutOutput, WorkspaceGitCheckoutRequest,
199    WorkspaceGitCommit, WorkspaceGitCreateBranchRequest, WorkspaceGitCreateWorktreeRequest,
200    WorkspaceGitDiffRequest, WorkspaceGitRemote, WorkspaceGitRemoveWorktreeRequest,
201    WorkspaceGitStash, WorkspaceGitStashProvider, WorkspaceGitStashRequest, WorkspaceGitStatus,
202    WorkspaceGitWorktree, WorkspaceGitWorktreeMutation, WorkspaceGitWorktreeProvider,
203    WorkspaceGlobRequest, WorkspaceGlobResult, WorkspaceGrepOutcome, WorkspaceGrepRequest,
204    WorkspaceGrepResult, WorkspacePath, WorkspacePathResolver, WorkspaceRef, WorkspaceResult,
205    WorkspaceSearch, WorkspaceServices, WorkspaceServicesBuilder, WorkspaceTextRange,
206    WorkspaceTextReader, WorkspaceVersionConflict, WorkspaceWriteOutcome,
207};
208#[cfg(feature = "s3")]
209pub use workspace::{S3BackendConfig, S3WorkspaceBackend};
a3s_code_core/lib.rs

a3s_code_core/
lib.rs
