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 patterns;
77pub mod permissions;
78pub mod policy;
79pub mod policy_gate;
80pub mod registry;
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;
136#[cfg(target_os = "macos")]
137pub use sandbox::MacosSandbox;
138pub use sandbox::{
139    NoopSandbox, Sandbox, SandboxError, SandboxPolicy, build_sandbox, build_sandbox_with_policy,
140};
141pub use schema_filter::{
142    DependencyExclusion, InclusionReason, ToolDependencyGraph, ToolEmbedding, ToolFilterResult,
143    ToolSchemaFilter,
144};
145pub use scope::{ScopeError, ScopeWarning, ScopedToolExecutor, ToolScope, build_scoped_executor};
146pub use scrape::WebScrapeExecutor;
147pub use search_code::{
148    LspSearchBackend, SearchCodeExecutor, SearchCodeHit, SearchCodeSource, SemanticSearchBackend,
149};
150pub use shadow_probe::{ProbeGate, ProbeOutcome, ShadowProbeExecutor};
151pub use shell::background::{BackgroundCompletion, BackgroundRunSnapshot, RunId};
152pub use shell::{
153    DEFAULT_BLOCKED_COMMANDS, SHELL_INTERPRETERS, ShellExecutor, ShellOutputEnvelope,
154    ShellPolicyHandle, check_blocklist, effective_shell_command,
155};
156pub use tool_filter::ToolFilter;
157pub use trust_gate::TrustGateExecutor;
158pub use trust_level::SkillTrustLevel;
159pub use utility::{
160    UtilityAction, UtilityContext, UtilityScore, UtilityScorer, has_explicit_tool_request,
161};
162pub use verifier::{
163    DestructiveCommandVerifier, FirewallVerifier, InjectionPatternVerifier, PreExecutionVerifier,
164    UrlGroundingVerifier, VerificationResult,
165};
166pub use zeph_common::ToolName;
167pub use zeph_config::tools::{
168    AdversarialPolicyConfig, AnomalyConfig, AuditConfig, AuthorizationConfig, DefaultEffect,
169    DependencyConfig, EgressConfig, FileConfig, FilterConfig, OverflowConfig, PolicyConfig,
170    PolicyEffect, PolicyRuleConfig, ResultCacheConfig, RetryConfig, SandboxConfig, SandboxProfile,
171    ScrapeConfig, SecurityFilterConfig, ShellConfig, TafcConfig, ToolDependency, ToolsConfig,
172    UtilityScoringConfig,
173};
174pub use zeph_config::tools::{
175    AutonomyLevel, PermissionAction, PermissionRule, PermissionsConfig, SpeculationMode,
176    SpeculativeAllowlistConfig, SpeculativeConfig, SpeculativePatternConfig,
177};
178pub use zeph_config::tools::{
179    DestructiveVerifierConfig, FirewallVerifierConfig, InjectionVerifierConfig,
180    PreExecutionVerifierConfig, UrlGroundingVerifierConfig,
181};
zeph_tools/lib.rs

zeph_tools/
lib.rs
