Web tools

Kin separates web discovery from exact-source reading. web_search and web_context can use Kinra’s hosted, provider-neutral retrieval capability or an explicit local Brave key. web_fetch runs directly from Kin and reads one URL without delegating retrieval to the hosted search service.

Enabling discovery

An official kinra-api connection can register web_search and web_context automatically after /login or a profile refresh. Kin requires the authenticated service profile to advertise the exact operation, uses only https://api.kinra.ai/v1/web/search and /v1/web/context, and never receives the underlying Brave or Exa key. The service advertises the capability only to a web-scoped device credential when at least one provider is configured. The tools appear or disappear live when login, logout, or profile refresh changes hosted-only availability; an explicit local key keeps them registered.

These fixed Gateway calls honor the configured HTTP(S) proxy just like Kinra sign-in. The same device key authorizes model access and hosted discovery; provider keys stay at Gateway.

/login status (and kin login status) reports which route is active from the same offline record: hosted through the login, an explicit local Brave override, or off. The login note says the same thing, including when a device key brought no hosted web access, the logout note says when hosted retrieval was withdrawn from the running session, and a background profile refresh that adds or removes the tools posts one note rather than changing the toolset silently.

Kin does not guess that the service is available when the profile omits kinra.ai/web-retrieval-profile/v1; use the local Brave route below in that case. A managed device credential created before hosted web was enabled remains inference-only. Once the capability is available, use /logout followed by /login (or deliberately replace the credential) to receive its web scope.

Local Brave override

/web-search opens the web-search status and configuration panel. When hosted retrieval is ready, a green card in the left column says Kinra Gateway · connected and names hosted Brave + Exa. The key field repeats Connected · key optional where it cannot be mistaken for a required setup step. Paste a Brave key and hit ++enter++ only when you want the self-managed direct-egress route; Kin saves it in the mode-0600 global credential store and registers both discovery tools live, with no restart. A local key remains useful without hosted access and becomes the explicit override when both routes are available.

The local key is resolved in this order:

Source	Key
Environment	BRAVE_API_KEY
Environment	KIN_BRAVE_API_KEY
Global credential store	brave_api_key in ~/.kin/credentials.toml

An explicit local key takes precedence over hosted routing and supports strategy=auto only. Remove the local key when you deliberately want the hosted semantic or diverse strategy. The key is global-only and is stripped from project settings. See Configuration and Environment variables.

BRAVE_API_KEY=BSA... uv run kin

With neither a local key nor an advertised hosted capability, only web_fetch appears in the discovery trio.

Shared provider keys

The service operator configures shared Brave and Exa credentials on console.kinra.ai under Search providers. The administrator surface shows only whether each provider is configured and when it changed; it never reads a key back or reveals its prefix, suffix, or length. Configure, replace, and remove are explicit operations separate from Kin login and device-key issuance.

web_search vs web_context vs web_fetch

Tool	Returns	Use when
web_search	Ranked, provider-labelled titles, URLs, snippets, and dates.	You want candidates, then plan to read the best source with web_fetch.
web_context	Provider-labelled, question-focused extractive passages grouped by source URL.	You want compact grounding across several sources.
web_fetch	Direct-retrieval metadata plus the main content of one exact URL as markdown, PDF text, or verbatim text.	You already have a URL or need to verify what one source actually says.

Both discovery tools take a query of at most 400 characters and 50 words, a bounded count, an optional freshness, and a provider-neutral strategy. The direct-Brave route retains two deliberately broader compatibility forms:

Argument	Hosted route	Explicit local Brave route
count	1–20 for both tools	1–20 for web_search; 1–50 for web_context
freshness	pd, pw, pm, or py	The same relative values, or a strict YYYY-MM-DDtoYYYY-MM-DD range with real ordered dates
strategy	auto, semantic, or diverse	auto only

The hosted strategies mean:

Strategy	Hosted behavior
auto	Prefer the general web lane, then fall back when it fails or has no usable result.
semantic	Prefer meaning-first retrieval, then fall back to the general lane.
diverse	Query every configured provider concurrently, retain partial success, deduplicate URLs, and interleave the result sets.

The hosted service currently maps the broad lane to Brave and the semantic lane to Exa, but those are operational choices rather than provider selectors in the tool contract. Provider labels remain visible provenance; they are not a truth or citation-validity guarantee. Ordinary auto and semantic calls do not spend both providers when the preferred one returns usable results.

web_context also accepts a max_tokens inline budget from 1024–32768 (default 8192). On the hosted route Kin applies that bound locally after the service returns its already bounded extractive passages. On the local-Brave route Kin also requests that upstream budget before applying the same local retention boundary.

web_fetch takes a url, an optional max_chars byte ceiling (default 50,000), and an optional focus question or topic with the same 400-character, 50-word bound as a discovery query. With focus, Kin deterministically ranks the extracted passages locally, preserves source order in the inline view, and offers the complete extracted capture to the session’s bounded read_spill store when persistence is enabled. Its marker reports when no ref was written or the store cap retained only part of that capture. The inline metadata names the requested URL, final URL, declared content type, response byte count, and extraction kind, so a focused selection cannot masquerade as a complete page.

A common pattern is web_search to find candidates, web_context to scan question-relevant evidence, and web_fetch to read or verify the best exact sources.

None of the tools can click, fill forms, run a general browser, retain cookies, or read an authenticated page. Hosted discovery is not a hidden remote-fetch fallback for web_fetch: its HTTP retrieval goes only to the validated source origin and its validated redirects. Kin does not separately delegate or copy that retrieval to a search provider or remote extractor. As with every tool result, the extracted text then becomes conversation content for the active model backend, which may itself be hosted.

A fourth, narrower tool, cite_check, verifies that already-cited URLs still resolve (HEAD-first, never downloading bodies, with a Wayback-snapshot substitute for dead ones). It is always registered, reuses web_fetch’s SSRF guard on every hop, and backs the deep-research citation-liveness gate.

SSRF safety

web_fetch only reaches public internet hosts. It blocks internal and loopback targets, so the model cannot use it to probe your network or a cloud metadata endpoint.

Concretely, the tool:

• Allows only http and https URLs and rejects embedded URL credentials.
• Resolves the hostname and validates every resolved address, rejecting loopback, link-local (including 169.254/16 cloud metadata), private, CGNAT, multicast, reserved, and unspecified ranges — and unwraps IPv4-mapped IPv6 so a wrapped loopback cannot slip through.
• Connects to the validated, pinned IP while preserving the requested Host authority (including an explicit non-default port) and TLS SNI, so a DNS-rebinding response cannot redirect the connection after the check. The direct client ignores ambient HTTP(S) proxy settings, so a proxy cannot replace that validated socket destination behind Kin’s back.
• Follows redirects manually and re-validates every hop, and caps the response size and redirect count.

A blocked address returns a plain error: blocked for safety result the model reads and moves on from; it is not a crash.

Discovery output likewise drops any result URL containing embedded credentials instead of preserving them in the conversation.

All three tools frame output as untrusted data before it enters the conversation, since titles, snippets, and page bodies are attacker-influenceable. For how that framing works, see the “Untrusted content” section of docs/invariants.md.