zeph_tools/
lib.rs

1// SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! Tool execution abstraction, shell backend, web scraping, and audit logging for Zeph.
5//!
6//! This crate provides the [`ToolExecutor`] trait and its concrete implementations:
7//!
8//! - [`ShellExecutor`] — executes bash blocks from LLM responses with sandboxing, blocklists,
9//!   output filtering, transactional rollback, and audit logging.
10//! - [`WebScrapeExecutor`] — fetches and scrapes web pages via CSS selectors, with SSRF
11//!   protection and domain policies.
12//! - [`CompositeExecutor`] — chains two executors with first-match-wins dispatch.
13//! - [`FileExecutor`] — reads and writes local files within a sandbox.
14//! - [`DiagnosticsExecutor`] — exposes agent self-diagnostics as a tool.
15//!
16//! # Architecture
17//!
18//! The primary abstraction is [`ToolExecutor`], an async trait implemented by every backend.
19//! When dynamic dispatch is needed (e.g., storing heterogeneous executors in a `Vec`), use
20//! [`ErasedToolExecutor`] or wrap with [`DynExecutor`].
21//!
22//! Tool calls originate from two paths:
23//!
24//! 1. **Fenced code blocks** — legacy LLM responses containing ` ```bash ` or ` ```scrape `
25//!    blocks dispatched via [`ToolExecutor::execute`].
26//! 2. **Structured tool calls** — modern JSON tool calls dispatched via
27//!    [`ToolExecutor::execute_tool_call`].
28//!
29//! # Security
30//!
31//! Every executor enforces security controls before execution:
32//!
33//! - [`ShellExecutor`] checks the command against a blocklist, validates paths against an
34//!   allowlist sandbox, and optionally requires user confirmation for destructive patterns.
35//! - [`WebScrapeExecutor`] validates the URL scheme (HTTPS only), resolves DNS, and rejects
36//!   private-network addresses (SSRF protection).
37//! - [`AuditLogger`] writes a structured JSONL entry for every tool invocation.
38//!
39//! # Example
40//!
41//! ```rust,no_run
42//! use zeph_tools::{ShellExecutor, ToolExecutor, ShellConfig};
43//!
44//! # async fn example() {
45//! let config = ShellConfig::default();
46//! let executor = ShellExecutor::new(&config);
47//!
48//! // Execute a fenced bash block from an LLM response.
49//! let response = "```bash\necho hello\n```";
50//! if let Ok(Some(output)) = executor.execute(response).await {
51//!     println!("{}", output.summary);
52//! }
53//! # }
54//! ```
55
56// TODO(critic): post-v1.0 — re-evaluate splitting executor / web / shell into sub-crates if compile times degrade.
57
58pub mod adversarial_gate;
59pub mod adversarial_policy;
60pub mod anomaly;
61pub mod audit;
62pub mod cache;
63pub mod composite;
64pub mod compression;
65pub mod config;
66pub mod cwd;
67pub mod diagnostics;
68pub mod domain_match;
69pub mod error_taxonomy;
70pub mod execution_context;
71pub mod executor;
72pub mod file;
73pub mod filter;
74pub mod moderation;
75pub mod net;
76pub mod permissions;
77pub mod policy;
78pub mod policy_gate;
79pub mod registry;
80pub mod risk_chain;
81pub mod sandbox;
82pub mod schema_filter;
83pub mod scope;
84pub mod scrape;
85pub mod search_code;
86pub mod shadow_probe;
87pub mod shell;
88pub mod tool_filter;
89pub mod trust_gate;
90pub mod trust_level;
91pub mod utility;
92pub mod verifier;
93pub use adversarial_gate::AdversarialPolicyGateExecutor;
94pub use adversarial_policy::{
95    PolicyDecision as AdversarialPolicyDecision, PolicyLlmClient, PolicyMessage, PolicyRole,
96    PolicyValidator, parse_policy_lines,
97};
98pub use anomaly::{AnomalyDetector, AnomalySeverity, is_reasoning_model};
99pub use audit::{
100    AuditEntry, AuditLogger, AuditResult, EgressEvent, VigilRiskLevel, chrono_now,
101    log_tool_risk_summary,
102};
103pub use cache::{CacheKey, ToolResultCache, is_cacheable};
104pub use composite::CompositeExecutor;
105pub use compression::{
106    CompressedExecutor, CompressionError, CompressionRule, CompressionRuleStore,
107    IdentityCompressor, OutputCompressor, RuleBasedCompressor, safe_compile,
108};
109pub use config::{build_permission_policy, validate_sandbox_denied_domains};
110pub use cwd::SetCwdExecutor;
111pub use diagnostics::DiagnosticsExecutor;
112pub use error_taxonomy::{
113    ErrorDomain, ToolErrorCategory, ToolErrorFeedback, ToolInvocationPhase, classify_http_status,
114    classify_io_error,
115};
116pub use execution_context::ExecutionContext;
117pub use executor::{
118    ClaimSource, DiffData, DynExecutor, ErasedToolExecutor, ErrorKind, FilterStats,
119    MAX_TOOL_OUTPUT_CHARS, TOOL_EVENT_CHANNEL_CAP, ToolCall, ToolError, ToolEvent, ToolEventRx,
120    ToolEventTx, ToolExecutor, ToolOutput, truncate_tool_output, truncate_tool_output_at,
121};
122pub use file::FileExecutor;
123pub use filter::{
124    CommandMatcher, FilterConfidence, FilterMetrics, FilterResult, OutputFilter,
125    OutputFilterRegistry, sanitize_output, strip_ansi,
126};
127pub use moderation::{
128    DeleteAllReactionsParams, DeleteReactionParams, ModerationError, ModerationExecutor,
129    ReactionModerationBackend,
130};
131pub use net::is_private_ip;
132pub use permissions::PermissionPolicy;
133pub use policy::{PolicyCompileError, PolicyContext, PolicyDecision, PolicyEnforcer};
134pub use policy_gate::{PolicyGateExecutor, RiskSignalQueue, TrajectoryRiskSlot};
135pub use registry::ToolRegistry;
136pub use risk_chain::{RiskChainAccumulator, RiskChainVerdict, RiskTag};
137#[cfg(target_os = "macos")]
138pub use sandbox::MacosSandbox;
139pub use sandbox::{
140    NoopSandbox, Sandbox, SandboxError, SandboxPolicy, build_sandbox, build_sandbox_with_policy,
141};
142pub use schema_filter::{
143    DependencyExclusion, InclusionReason, ToolDependencyGraph, ToolEmbedding, ToolFilterResult,
144    ToolSchemaFilter,
145};
146pub use scope::{ScopeError, ScopeWarning, ScopedToolExecutor, ToolScope, build_scoped_executor};
147pub use scrape::WebScrapeExecutor;
148pub use search_code::{
149    LspSearchBackend, SearchCodeExecutor, SearchCodeHit, SearchCodeSource, SemanticSearchBackend,
150};
151pub use shadow_probe::{ProbeGate, ProbeOutcome, ShadowProbeExecutor};
152pub use shell::background::{BackgroundCompletion, BackgroundRunSnapshot, RunId};
153pub use shell::{
154    DEFAULT_BLOCKED_COMMANDS, SHELL_INTERPRETERS, SafeFixSuggestion, ShellExecutor,
155    ShellOutputEnvelope, ShellPolicyHandle, check_blocklist, deobfuscate_command,
156    effective_shell_command, is_blocked_rm_worktrees,
157};
158pub use tool_filter::ToolFilter;
159pub use trust_gate::TrustGateExecutor;
160pub use trust_level::SkillTrustLevel;
161pub use utility::{
162    UtilityAction, UtilityContext, UtilityScore, UtilityScorer, has_explicit_tool_request,
163};
164pub use verifier::{
165    DestructiveCommandVerifier, FirewallVerifier, InjectionPatternVerifier, PreExecutionVerifier,
166    UrlGroundingVerifier, VerificationResult,
167};
168pub use zeph_common::ToolName;
169pub use zeph_config::tools::{
170    AdversarialPolicyConfig, AnomalyConfig, AuditConfig, AuditDestination, AuthorizationConfig,
171    DefaultEffect, DependencyConfig, EgressConfig, FileConfig, FilterConfig, OverflowConfig,
172    PolicyConfig, PolicyEffect, PolicyRuleConfig, ResultCacheConfig, RetryConfig, SandboxConfig,
173    SandboxProfile, ScrapeConfig, SecurityFilterConfig, ShellConfig, TafcConfig, ToolDependency,
174    ToolsConfig, UtilityScoringConfig,
175};
176pub use zeph_config::tools::{
177    AutonomyLevel, PermissionAction, PermissionRule, PermissionsConfig, SpeculationMode,
178    SpeculativeAllowlistConfig, SpeculativeConfig, SpeculativePatternConfig,
179};
180pub use zeph_config::tools::{
181    DestructiveVerifierConfig, FirewallVerifierConfig, InjectionVerifierConfig,
182    PreExecutionVerifierConfig, UrlGroundingVerifierConfig,
183};
zeph_tools/lib.rs

zeph_tools/
lib.rs
