Documentation
¶
Overview ¶
Package websearch implements the WebSearch tool and its SearchProvider seam, with no filesystem access. Preparation turns every HTTPS endpoint the bound provider declares into one shared `network` capability requirement (the same capability kind Bash network deltas and Fetch use); at run time the provider must fail closed on any target outside its declaration.
Index ¶
- type DuckDuckGoProvider
- type Endpoint
- type SearchProvider
- type SearchResult
- type WebSearch
- func (w *WebSearch) AuditSummary(argsJSON string) string
- func (w *WebSearch) Info(context.Context) (*tool.ToolInfo, error)
- func (w *WebSearch) InvokableRun(ctx context.Context, _ string) (*tool.ToolResult, error)
- func (w *WebSearch) PrepareCall(_ context.Context, executionID uuid.UUID, argsJSON string) (tool.Request, tool.PreparedArtifact, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DuckDuckGoProvider ¶
type DuckDuckGoProvider struct {
// contains filtered or unexported fields
}
DuckDuckGoProvider is a SearchProvider that scrapes DuckDuckGo's HTML results page. It depends only on an *http.Client (least privilege — no filesystem).
func NewDuckDuckGoProvider ¶
func NewDuckDuckGoProvider(client *http.Client) *DuckDuckGoProvider
NewDuckDuckGoProvider constructs a DuckDuckGoProvider bound to an injected *http.Client. The client is expected to carry an explicit Timeout and a TLS 1.2+ Transport (wired at the manifest); the provider never builds a client.
func (*DuckDuckGoProvider) Endpoints ¶
func (p *DuckDuckGoProvider) Endpoints() []Endpoint
Endpoints declares the ONLY network endpoint this provider contacts: https://html.duckduckgo.com:443 (the scrape target ddgHTMLEndpoint). The WebSearch tool turns it into the prepared network requirement; Search confines its client to it so a redirect to any secondary target fails closed.
func (*DuckDuckGoProvider) Search ¶
func (p *DuckDuckGoProvider) Search(ctx context.Context, query string, max int) ([]SearchResult, error)
Search GETs the DuckDuckGo HTML results page for query under ctx and parses up to max results. A request-build, transport, or non-2xx-status failure is a typed *searchProviderError; a successful response is parsed defensively (a malformed body yields whatever parsed, never a panic).
type Endpoint ¶
Endpoint is one HTTPS network endpoint a SearchProvider talks to: the normalized hostname (lowercase, no trailing dot) and TCP port. Preparation turns every declared endpoint into a shared `network` capability requirement; at run time the provider must fail closed on any secondary target (a redirect or auxiliary service) outside this declaration.
type SearchProvider ¶
type SearchProvider interface {
Search(ctx context.Context, query string, max int) ([]SearchResult, error)
Endpoints() []Endpoint
}
SearchProvider is the seam between the WebSearch tool and a concrete search backend (DuckDuckGo today; pluggable tomorrow). Search runs under ctx (the implementation MUST honor its deadline/cancellation), takes the query and a caller-validated max (already clamped to (0, maxWebSearchResults]), and returns up to max results or a typed error. An implementation must never panic on a malformed upstream response — it returns what it could parse.
Endpoints declares every network endpoint Search may contact. It must be stable and non-empty; a provider that cannot honestly enumerate its endpoints cannot be prepared and fails closed.
type SearchResult ¶
SearchResult is one web search hit: a human title, the result URL, and a short snippet. It is the provider-agnostic value the SearchProvider yields and the WebSearch tool formats.
type WebSearch ¶
type WebSearch struct {
// contains filtered or unexported fields
}
WebSearch performs a web search via an injected SearchProvider. It has no filesystem access (least privilege).
func NewWebSearch ¶
func NewWebSearch(provider SearchProvider) *WebSearch
NewWebSearch constructs a WebSearch tool bound to a SearchProvider.
func (*WebSearch) AuditSummary ¶
AuditSummary returns "WebSearch: <query>" — the query is exactly what the user approves at the gate, so it is the right (and only) summary. An unparseable args document yields a generic summary.
func (*WebSearch) InvokableRun ¶
InvokableRun executes the PREPARED artifact bound to this call — the raw argsJSON is never reparsed; without its artifact the tool fails closed. It calls the provider under ctx and formats the results. A provider error is a tool-result error STRING; it never returns a Go error.
func (*WebSearch) PrepareCall ¶
func (w *WebSearch) PrepareCall(_ context.Context, executionID uuid.UUID, argsJSON string) (tool.Request, tool.PreparedArtifact, error)
PrepareCall decodes and validates one WebSearch call and emits the shared `network` capability requirement for EVERY endpoint the bound provider declares. The grant pair is empty: WebSearch is a direct tool and its provider confines its own requests to the declared endpoints (secondary targets fail closed at run time).
Source Files