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

a3s_code_core/
lib.rs
