Crate plugin_web 

Web access for prompts: a Plugin that gives a run two tools, one that fetches a page and one that searches the web.

A Host installs PACKAGE, by default under the name web, and every run then receives both tools: web/fetch, which fetches a URL and returns its content as text, and web/search, which runs a search through the Host’s SearchProvider. The two tools always come together, named under whatever name the Host installed the Plugin under.

The Plugin has no prelude, so declaring it, as in plugins: [web], only makes it required. A prompt reaches the tools by id from Lua, offering one to the model with tools.offer("web/fetch") or calling it with tools.call("web/search", ...), whether or not it declares the Plugin.

The Host provides two Host-wide services beside the Plugin. Its SearchProvider goes under the key SEARCH_PROVIDER, and the tokio runtime handle that every fetch is spawned onto goes under the Plugin contract’s [runvil_plugin::TOKIO_RUNTIME] service. Install reads both; when either is missing, the Plugin is installed as unavailable, no run receives its tools, and a prompt that declares it is refused naming the missing service.

The fetch tool is security-critical. The model supplies the URL, so the tool is the server-side request forgery (SSRF) boundary between an untrusted argument and the network. It enforces the built-in default fetch policy.

The fetch tool sends a GET request and chooses how to render the response from its Content-Type. For an HTML page, it extracts the main article with readabilityrs and renders it to markdown. When a page yields too little article text, htmd converts the whole page to markdown. Any other text body, such as JSON, XML, or plain text, is decoded and returned verbatim. The tool refuses every other type.

The search tool validates the model’s arguments into a SearchQuery and hands it to the provider. It returns the provider’s SearchResults as compact JSON, marked untrusted. The JSON matches the Gateway’s search output: an object with the query and a results array. Each result has a title, url, and description, plus age, site_name, and extra_snippets when present. The provider owns the transport and its deadline, so a search vendor’s credential stays wherever the provider keeps it.

Invariants

• May depend on: runvil-plugin, shared-* crates, and outside libraries. cargo test -p build-xtask enforces the Plugin family’s allow-list.
• Every URL selected by the model or a tool, and every resolved address, is validated again on each redirect hop. A non-global address is denied unless the fetch policy grants an exact host-and-address exception.
• No fetch includes an ambient identity on any hop. The client has no proxy, no cookie store, no automatic Referer header, and no default credentials.
• Every fetch runs on the Host’s runtime handle, and dropping the call aborts it.
• Install accepts only a null or {} configuration; any other value leaves the Plugin unavailable.

Structs

SearchError

The error a SearchProvider returns when a search fails.

SearchQuery

The validated arguments of one web/search call.

SearchResult

One result in SearchResults: a title, a URL, a description, and optional extras.

SearchResults

The results a SearchProvider returns for one search, with the query it ran.

Enums

Freshness

How recent the results of a SearchQuery must be.

SafeSearch

The SafeSearch filtering level of a SearchQuery.

SearchErrorKind

Which part of a search failed: the transport or the backend.

Constants

PACKAGE

The Plugin’s label, which a Host adds to its package registry.

SEARCH_PROVIDER

The service key for the Host’s search provider.

Traits

SearchProvider

A backend that runs web searches for the web/search tool.