a3s-code-core 2.2.0

A3S Code Core - Embeddable AI agent library with tool execution
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

//! AHP (Agent Harness Protocol) Integration
//!
//! Provides external supervision and governance for A3S Code agents via the
//! Agent Harness Protocol v2.3. This module bridges A3S Code's hook system
//! with AHP's event-driven supervision model.
//!
//! ## Overview
//!
//! AHP enables external harness servers to:
//! - Intercept and validate agent actions before execution
//! - Monitor agent behavior and outputs
//! - Enforce depth-aware policies for nested agents
//! - Query agents for guidance on ambiguous operations
//! - Batch process multiple events for efficiency
//! - **Detect idle state** for background consolidation (dream system)
//! - **Context-aware decisions** with rich session context
//!
//! ## Architecture
//!
//! ```text
//! A3S Code Agent
//!   └── HookEngine
//!         └── AhpHookExecutor (implements HookExecutor)
//!               ├── Idle Tracker (fires Idle events when agent is idle)
//!               ├── EventContext Builder (enriches events with memory/facts)
//!               └── AhpClient
//!                     └── Transport (stdio / HTTP / WebSocket)
//!                           └── External Harness Server
//! ```
//!
//! ## Usage
//!
//! ```rust,no_run
//! use a3s_code_core::{Agent, SessionOptions};
//! use a3s_code_core::ahp::{AhpHookExecutor, AhpTransport};
//!
//! # async fn example() -> anyhow::Result<()> {
//! // Create AHP executor with HTTP transport and 10s idle threshold
//! let ahp = AhpHookExecutor::new_with_config(
//!     AhpTransport::Http {
//!         url: "http://localhost:8080/ahp".to_string(),
//!         auth: None,
//!     },
//!     10_000  // 10 second idle threshold
//! ).await?;
//!
//! // Create agent with AHP supervision
//! let agent = Agent::new("agent.acl").await?;
//! let session = agent.session(
//!     "/workspace",
//!     Some(SessionOptions::default().with_hook_executor(std::sync::Arc::new(ahp)))
//! )?;
//!
//! // All agent actions are now supervised by the harness
//! session.send("Refactor auth module", None).await?;
//! # Ok(())
//! # }
//! ```
//!
//! ## Event Mapping
//!
//! A3S Code hooks are mapped to AHP events:
//!
//! | A3S Code Hook | AHP Event | Blocking |
//! |---------------|-----------|----------|
//! | `PreToolUse` | `PreAction` | Yes |
//! | `PostToolUse` | `PostAction` | No |
//! | `PrePrompt` | `PrePrompt` | Yes |
//! | `GenerateStart` | `PrePrompt` | Yes |
//! | `PostResponse` | `PostAction` | No |
//! | `SessionStart` | `SessionStart` | No |
//! | `SessionEnd` | `SessionEnd` | No |
//! | `OnError` | `Error` | No |
//! | `AgentEvent::Start` | `RunLifecycle(executing)` | No |
//! | `AgentEvent::PlanningStart` | `RunLifecycle(planning)` | No |
//! | `AgentEvent::TaskUpdated` | `TaskList` | No |
//! | `AgentEvent::End` | `RunLifecycle(completed)` + `Verification` | No |
//! | `AgentEvent::Error` | `RunLifecycle(failed)` | No |
//!
//! ## Idle Detection (Dream System)
//!
//! When idle detection is enabled, AHP fires `Idle` events when the agent
//! has been inactive for a configurable threshold duration. This enables:
//! - Background memory consolidation
//! - Cross-session fact processing
//! - Periodic cleanup and optimization
//!
//! The harness server can respond with `IdleDecision::Allow` to permit
//! background consolidation or `IdleDecision::Defer` to postpone it.
//!
//! ## Depth-Aware Policies
//!
//! AHP supports depth tracking for nested agents:
//! - Depth 0: User-initiated agent
//! - Depth 1: First-level sub-agent
//! - Depth 2+: Deeply nested agents
//!
//! Harness servers can enforce stricter policies at higher depths.

#[cfg(feature = "ahp")]
mod contract;
#[cfg(feature = "ahp")]
mod executor;

#[cfg(feature = "ahp")]
pub use contract::{agent_event_to_ahp_events, cancelled_run_event, tasks_to_ahp_items};
#[cfg(feature = "ahp")]
pub use executor::AhpHookExecutor;

#[cfg(feature = "ahp")]
pub use a3s_ahp::{
    AhpClient, AhpError, AhpEvent, AhpNotification, AhpRequest, AhpResponse, ArtifactRef,
    AuthConfig, ConfirmationDecision, ContextPerceptionDecision, ContextPerceptionEvent, Decision,
    EventContext, EventType, EvidenceRef, Fact, HeartbeatEvent, IdleDecision, IdleEvent,
    InjectedContext, IntentDetectionDecision, IntentDetectionEvent, MemoryRecallDecision,
    MemoryRecallEvent, MemorySummary, PerceptionConstraints, PerceptionContext, PerceptionDomain,
    PerceptionFreshness, PerceptionIntent, PerceptionModality, PerceptionTarget, PerceptionUrgency,
    PlanningDecision, PlanningEvent, QueryRequest, QueryResponse, RateLimitDecision,
    RateLimitEvent, ReasoningDecision, ReasoningEvent, RunLifecycleEvent, RunStatus, SessionStats,
    SuccessEvent, TargetHints, TaskItem, TaskListEvent, TaskStatus, Transport as AhpTransport,
    VerificationCheck, VerificationEvent, VerificationStatus, PROTOCOL_VERSION,
};

// Re-export types from protocol that are not directly in a3s_ahp root
#[cfg(feature = "ahp")]
pub use a3s_ahp::protocol::{
    ConfirmationEvent, ConfirmationType, PlanningStrategy, RateLimitType, ReasoningType,
};

#[cfg(not(feature = "ahp"))]
compile_error!("AHP feature is not enabled. Add `ahp` feature to use this module.");