apomesh-substrate-tools

apomesh-substrate-tools is a substrate implementation plane: the concrete leaf tools an agent actually dispatches — web fetch/search, file operations, git, shell — plus the predicate verification evaluator, all behind the Tool / TenantSecrets / Predicate ports defined in apomesh-substrate-types. It is a capabilities plane, not a policy plane: it says what a tool does, never who may run it, how it is isolated, or where its secret comes from. Touch it to add or evolve a substrate-shipped tool; touch the runtime, the sandbox plane, or the credential plane for the policy those tools run under.

Position in the workspace

• Layer: substrate implementation plane. See Control & execution planes.
• Depends on: apomesh-substrate-types (the Tool, TenantSecrets, and Predicate ports these tools implement), apomesh-substrate-net (the shared webpki reqwest client the web tools build on), and apomesh-substrate-sandbox (the SandboxedCommand primitive the shell and git tools compose). It does not depend on the LLM plane — the LLMProvider port lives in -types, and the binaries inject the concrete provider at construction.
• Consumed by: apomesh-substrate, which re-exports the whole plane through its tool and predicate facades, so consumers keep reaching apomesh_substrate::tool::* and apomesh_substrate::predicate::* unchanged.

What it owns

The substrate-shipped tool inventory — the concrete Tool impls behind the port:

Tool(s)	What it does	Notable posture
WebFetchTool (web_fetch/native)	HTTP GET a URL, follow redirects, extract text	Read-only; a tool-less ingress qualifier vets every page before an acting agent sees it (fail-closed); a connect-time SSRF guard; fetch failures return as tool content, not errors
WebSearchTool (web_search/native/{serper,brave})	Call an external search vendor directly	Provider selected by tool id — Serper (Google SERP proxy) or Brave (first-party); no vendor-shaped type leaks to the agent
WrappedWebSearchTool (web_search/client/<provider>)	Give any model provider-grade search via a one-shot internal LLM call	Returns the internal call’s spend on ToolOutput::with_cost so the worker emits the CostEvent
FileReadTool / FileWriteTool / FileCreateTool / FileDeleteTool / FileMoveTool	Read/write/create/delete/move under the workspace root	WorkspacePathResolver gates path safety; the four mutating tools are SideEffectingTool for resume-idempotent replay
git.status / git.diff / git.commit / git.branch / git.log	Substrate-shipped git subcommands	Built as CliTool instances; reads are read-only, git.commit is side-effecting
ShellExecTool (shell.exec) + CliTool	Run a shell command or an operator-defined command template	Compose SandboxedCommand + the workspace resolver + per-tenant TenantSecrets injection
PredicateEvaluator	Evaluate a Predicate to a substrate-owned verdict	The verification engine (holds live provider + fetcher handles); the Predicate vocabulary itself lives in -types

It does not own sandbox policy (that is apomesh-substrate-sandbox), credential resolution (the orchestrator resolves each secret from the one CredentialStore per TenantContext), or tool registration and routing — per-session ToolRegistry instances and the runtime-state tools (checkpoint, lifecycle, procedural) stay in the runtime.

Public surface

• WebFetchTool — the ingress-qualified native fetch tool; with_provider injects the qualifier’s LLMProvider.
• WebSearchTool — the direct-vendor search tool; serper() / a Brave provider select the backend.
• WrappedWebSearchTool — server-tool-grade search for any model via an internal one-shot LLM call.
• qualify + QualifierProviderFactory — the shared text-to-action firebreak: distil an untrusted page to a TrustVerdict, fail-closed.
• register_file_tools — register the five workspace file tools against a WorkspacePathResolver.
• register_git_tools / register_shell_tools — register the substrate-shipped git and shell tools.
• CliToolBuilder — build an operator-defined CliTool from a [[cli_tools]] command template.
• WorkspacePathResolver — resolve a caller path against the workspace root, rejecting escape and absolute-outside-root.
• PredicateEvaluator — the predicate evaluation engine returning strict, substrate-owned verdicts.

Usage

Tools are constructed with their injected dependencies and registered into a ToolRegistry at daemon startup. The orchestrator binary registers the workspace file tools once it resolves APOMESH_WORKSPACE_ROOT:

use std::sync::Arc;
use apomesh_substrate::tool::{register_file_tools, WorkspacePathResolver};

// Resolved once at startup from APOMESH_WORKSPACE_ROOT.
let resolver = Arc::new(WorkspacePathResolver::from_env()?);
register_file_tools(session.tool_registry(), resolver);

Tools never read a credential from process env. A tool that needs a secret declares its name via Tool::required_secrets; the orchestrator resolves it from the per-tenant CredentialStore and forwards it, typed, on the transient dispatch channel, so the tool reads it from ToolContext.secrets inside the sandbox — never from the ambient environment. See The credential plane for the full path.

Related

• Concepts: The credential plane (how a resolved secret reaches a tool), Control & execution planes (the decide / route / execute split these tools sit at the leaf of).
• Reference: apomesh-substrate-sandbox (the isolation every dispatch runs inside), apomesh-substrate-types (the Tool / TenantSecrets / Predicate ports this plane implements), apomesh-worker (the layer that drives a tool dispatch through the sandbox).