iii / worker
$worker

web

v1.2.3

Outbound HTTP client on the iii bus (web::fetch).

  • macOS: arm64 · x64
  • Linux: arm64 · armv7 · x64
  • Windows: arm64 · x64 · x86

functions

3

web::fetch

function

Fetch a URL over HTTP(S) and return the response as a structured envelope. Use this INSTEAD of `shell::exec` with curl for any HTTP request — it returns {ok, status, headers, body} as JSON, enforces size/timeout caps, and blocks private / cloud-metadata / link-local addresses server-side (SSRF guard; loopback is allowed by default for harness dev workflows). To READ A WEB PAGE, set `format: "markdown"` — HTML is converted to Markdown and images come back viewable (image responses in that mode return the image itself plus a text line, not the {ok,...} envelope). For JSON: pass `json: {...}` (auto-stringifies + sets content-type) and `response_format: "json"` (auto-parses response into the `json` field). Method is case-insensitive. On failure returns `{ok:false, error, message}` where `error` is one of: invalid_payload, invalid_url, blocked_host, timeout, too_many_redirects, transport_error. Branch on `error`, not on text.

request
  • bodystring

    Raw request body as a string. Prefer `json` for JSON payloads.

  • content_filterany of

    Content filter: prunes boilerplate. When set, `body` holds the filtered output in the requested `format` (page-reading mode only).

    any of (2)
    variant 1
    • min_word_thresholdinteger· uint32min 0
    • querystring
    • thresholdnumber· double
    • threshold_typeany of
      … expand 2 nested
      any of (2)
      variant 1
      valuestringenum: fixed, dynamic
      variant 2
      valuenull
    • typestringrequiredenum: pruning, bm25
    variant 2
    valuenull
  • excluded_tagsstring[]

    Tag names / selectors to drop before rendering (e.g. "nav", "footer").

  • follow_redirectsboolean

    Follow 3xx redirects. Defaults to true. Each hop is re-checked against the SSRF blocklist.

  • formatany of

    Page-reading mode: "markdown" | "text" | "html". When set, a browser UA + format Accept header are used, HTML is transformed, and response_format is ignored (treated as "text").

    any of (2)
    variant 1
    valuestringenum: markdown, text, html
    variant 2
    valuenull
  • headersobject

    Request headers. Lower-cased keys recommended.

  • include_linksboolean

    Add `links: { internal, external }` to the envelope.

  • include_mediaboolean

    Add `media: { images, videos, audios }` to the envelope.

  • jsonunknown

    Structured JSON payload. When set, the handler stringifies it and forces `content-type: application/json`; wins over `body`.

  • max_bytesinteger· uint64min 0

    Cap on response body bytes. Defaults to the worker ceiling for raw fetches, or 256 KiB in page-reading mode (`format` set).

  • methodstring

    HTTP method. Defaults to GET. Case-insensitive ("get" works).

  • response_formatany of

    How to return the body: "text" (default), "base64", or "json".

    any of (2)
    variant 1
    valuestringenum: text, base64, json
    variant 2
    valuenull
  • target_elementsstring[]

    CSS selectors (tl subset: tag/.class/#id). Restrict rendered content to these regions. Unmatched selectors are ignored.

  • timeout_msinteger· uint64min 0

    Per-request timeout in ms. Capped by the worker's max_timeout_ms.

  • urlstringrequired

    Absolute http(s):// URL to fetch.

response
  • bodystring
  • bytes_truncatedboolean
  • contentunknown
  • content_typestring
  • detailsunknown
  • errorstring
  • headersobject
  • jsonunknown
  • linksunknown
  • mediaunknown
  • messagestring
  • okboolean
  • parse_errorstring
  • redirect_chainstring[]
  • response_formatstring
  • statusinteger· uint16min 0
  • status_textstring
  • transformedstring

web::inject-guidance

function

Internal pre_generate hook: appends web::fetch usage guidance to the agent system prompt. Bound to harness::hook::pre-generate at worker startup; not called directly.

request
  • generateobject
    • system_promptstring

      The system prompt assembled so far (base + any prior hook's mutation).

response
  • mutationsobjectrequired

    The harness applies `system_prompt` only when the key is present (`HookRunner::run_pre_generate` — `if m.system_prompt.is_some()`), so `None` serializes to an empty object: the safe no-op that preserves the harness's assembled prompt.

    • system_promptstring

      Full replacement system prompt (base + appended guidance). The harness overwrites, it does not merge.

web::on-config-change

function

Internal: reload web settings from the authoritative configuration on change.

request
empty object
response
  • okbooleanrequired

triggers

0
no triggers registered