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

zeph_tools/
lib.rs
