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

a3s_code_core/
lib.rs
