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    CheckpointActionResult, CheckpointEntryView, CheckpointListResult, ClaimSource, DiffData,
119    DynExecutor, ErasedToolExecutor, ErrorKind, FilterStats, MAX_TOOL_OUTPUT_CHARS,
120    TOOL_EVENT_CHANNEL_CAP, ToolCall, ToolError, ToolEvent, ToolEventRx, ToolEventTx, ToolExecutor,
121    ToolOutput, truncate_tool_output, truncate_tool_output_at,
122};
123pub use file::FileExecutor;
124pub use filter::{
125    CommandMatcher, FilterConfidence, FilterMetrics, FilterResult, OutputFilter,
126    OutputFilterRegistry, sanitize_output, strip_ansi,
127};
128pub use moderation::{
129    DeleteAllReactionsParams, DeleteReactionParams, ModerationError, ModerationExecutor,
130    ReactionModerationBackend,
131};
132pub use net::is_private_ip;
133pub use permissions::PermissionPolicy;
134pub use policy::{PolicyCompileError, PolicyContext, PolicyDecision, PolicyEnforcer};
135pub use policy_gate::{PolicyGateExecutor, RiskSignalQueue, TrajectoryRiskSlot};
136pub use registry::ToolRegistry;
137pub use risk_chain::{RiskChainAccumulator, RiskChainVerdict, RiskTag};
138#[cfg(target_os = "macos")]
139pub use sandbox::MacosSandbox;
140pub use sandbox::{
141    NoopSandbox, Sandbox, SandboxError, SandboxPolicy, build_sandbox, build_sandbox_with_policy,
142};
143pub use schema_filter::{
144    DependencyExclusion, InclusionReason, ToolDependencyGraph, ToolEmbedding, ToolFilterResult,
145    ToolSchemaFilter,
146};
147pub use scope::{ScopeError, ScopeWarning, ScopedToolExecutor, ToolScope, build_scoped_executor};
148pub use scrape::WebScrapeExecutor;
149pub use search_code::{
150    LspSearchBackend, SearchCodeExecutor, SearchCodeHit, SearchCodeSource, SemanticSearchBackend,
151};
152pub use shadow_probe::{ProbeGate, ProbeOutcome, ShadowProbeExecutor};
153pub use shell::background::{BackgroundCompletion, BackgroundRunSnapshot, RunId};
154pub use shell::{
155    DEFAULT_BLOCKED_COMMANDS, SHELL_INTERPRETERS, SafeFixSuggestion, ShellExecutor,
156    ShellOutputEnvelope, ShellPolicyHandle, check_blocklist, deobfuscate_command,
157    effective_shell_command, is_blocked_rm_worktrees,
158};
159pub use tool_filter::ToolFilter;
160pub use trust_gate::TrustGateExecutor;
161pub use trust_level::SkillTrustLevel;
162pub use utility::{
163    UtilityAction, UtilityContext, UtilityScore, UtilityScorer, has_explicit_tool_request,
164};
165pub use verifier::{
166    DestructiveCommandVerifier, FirewallVerifier, InjectionPatternVerifier, PreExecutionVerifier,
167    UrlGroundingVerifier, VerificationResult,
168};
169pub use zeph_common::ToolName;
170pub use zeph_config::tools::{
171    AdversarialPolicyConfig, AnomalyConfig, AuditConfig, AuditDestination, AuthorizationConfig,
172    DefaultEffect, DependencyConfig, EgressConfig, FileConfig, FilterConfig, OverflowConfig,
173    PolicyConfig, PolicyEffect, PolicyRuleConfig, ResultCacheConfig, RetryConfig, SandboxConfig,
174    SandboxProfile, ScrapeConfig, SecurityFilterConfig, ShellConfig, TafcConfig, ToolDependency,
175    ToolsConfig, UtilityScoringConfig,
176};
177pub use zeph_config::tools::{
178    AutonomyLevel, PermissionAction, PermissionRule, PermissionsConfig, SpeculationMode,
179    SpeculativeAllowlistConfig, SpeculativeConfig, SpeculativePatternConfig,
180};
181pub use zeph_config::tools::{
182    DestructiveVerifierConfig, FirewallVerifierConfig, InjectionVerifierConfig,
183    PreExecutionVerifierConfig, UrlGroundingVerifierConfig,
184};
zeph_tools/lib.rs

zeph_tools/
lib.rs
