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

a3s_code_core/
lib.rs
