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

a3s_code_core/
lib.rs
