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
//! AHP (Agent Harness Protocol) Integration
//!
//! Provides external supervision and governance for A3S Code agents via the
//! Agent Harness Protocol v2.0. 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("http://localhost:8080/ahp", None),
//! 10_000 // 10 second idle threshold
//! ).await?;
//!
//! // Create agent with AHP supervision
//! let agent = Agent::new("agent.hcl").await?;
//! let session = agent.session(
//! "/workspace",
//! Some(SessionOptions::default().with_ahp_executor(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 |
//!
//! ## 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.
pub use AhpHookExecutor;
pub use ;
compile_error!;