{
  "functions": [
    {
      "description": "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.",
      "metadata": {},
      "name": "web::fetch",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "ContentFilter": {
            "description": "Content-filter request block. `query`, `threshold`, `threshold_type`, and `min_word_threshold` are optional; their default values are applied when the filter runs (see the content pipeline), not at deserialization.",
            "properties": {
              "min_word_threshold": {
                "default": null,
                "format": "uint32",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "query": {
                "default": null,
                "type": [
                  "string",
                  "null"
                ]
              },
              "threshold": {
                "default": null,
                "format": "double",
                "type": [
                  "number",
                  "null"
                ]
              },
              "threshold_type": {
                "anyOf": [
                  {
                    "$ref": "#/definitions/ThresholdType"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "type": {
                "$ref": "#/definitions/FilterType"
              }
            },
            "required": [
              "type"
            ],
            "type": "object"
          },
          "FilterType": {
            "enum": [
              "pruning",
              "bm25"
            ],
            "type": "string"
          },
          "PageFormat": {
            "enum": [
              "markdown",
              "text",
              "html"
            ],
            "type": "string"
          },
          "ResponseFormat": {
            "enum": [
              "text",
              "base64",
              "json"
            ],
            "type": "string"
          },
          "ThresholdType": {
            "enum": [
              "fixed",
              "dynamic"
            ],
            "type": "string"
          }
        },
        "properties": {
          "body": {
            "default": null,
            "description": "Raw request body as a string. Prefer `json` for JSON payloads.",
            "type": [
              "string",
              "null"
            ]
          },
          "content_filter": {
            "anyOf": [
              {
                "$ref": "#/definitions/ContentFilter"
              },
              {
                "type": "null"
              }
            ],
            "description": "Content filter: prunes boilerplate. When set, `body` holds the filtered output in the requested `format` (page-reading mode only)."
          },
          "excluded_tags": {
            "default": null,
            "description": "Tag names / selectors to drop before rendering (e.g. \"nav\", \"footer\").",
            "items": {
              "type": "string"
            },
            "type": [
              "array",
              "null"
            ]
          },
          "follow_redirects": {
            "default": null,
            "description": "Follow 3xx redirects. Defaults to true. Each hop is re-checked against the SSRF blocklist.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "format": {
            "anyOf": [
              {
                "$ref": "#/definitions/PageFormat"
              },
              {
                "type": "null"
              }
            ],
            "description": "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\")."
          },
          "headers": {
            "additionalProperties": {
              "type": "string"
            },
            "default": null,
            "description": "Request headers. Lower-cased keys recommended.",
            "type": [
              "object",
              "null"
            ]
          },
          "include_links": {
            "default": null,
            "description": "Add `links: { internal, external }` to the envelope.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "include_media": {
            "default": null,
            "description": "Add `media: { images, videos, audios }` to the envelope.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "json": {
            "default": null,
            "description": "Structured JSON payload. When set, the handler stringifies it and forces `content-type: application/json`; wins over `body`."
          },
          "max_bytes": {
            "default": null,
            "description": "Cap on response body bytes. Defaults to the worker ceiling for raw fetches, or 256 KiB in page-reading mode (`format` set).",
            "format": "uint64",
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          },
          "method": {
            "default": null,
            "description": "HTTP method. Defaults to GET. Case-insensitive (\"get\" works).",
            "type": [
              "string",
              "null"
            ]
          },
          "response_format": {
            "anyOf": [
              {
                "$ref": "#/definitions/ResponseFormat"
              },
              {
                "type": "null"
              }
            ],
            "description": "How to return the body: \"text\" (default), \"base64\", or \"json\"."
          },
          "target_elements": {
            "default": null,
            "description": "CSS selectors (tl subset: tag/.class/#id). Restrict rendered content to these regions. Unmatched selectors are ignored.",
            "items": {
              "type": "string"
            },
            "type": [
              "array",
              "null"
            ]
          },
          "timeout_ms": {
            "default": null,
            "description": "Per-request timeout in ms. Capped by the worker's max_timeout_ms.",
            "format": "uint64",
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          },
          "url": {
            "description": "Absolute http(s):// URL to fetch.",
            "type": "string"
          }
        },
        "required": [
          "url"
        ],
        "title": "FetchPayload",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "description": "Typed schema for the `web::fetch` response envelope. The handler returns a raw `Value` (its shape is request-dependent), so this type exists only to publish a concrete response schema: the SDK would otherwise emit the permissive `AnyValue` schema, which the registry rejects. Every field is optional because no single response carries all of them — success carries `ok`/`status`/`headers`/`body`/…, the page-mode viewable-image variant carries `content`+`details`, and failures carry `ok=false`/`error`/`message`.",
        "properties": {
          "body": {
            "type": [
              "string",
              "null"
            ]
          },
          "bytes_truncated": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "content": true,
          "content_type": {
            "type": [
              "string",
              "null"
            ]
          },
          "details": true,
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "headers": {
            "additionalProperties": {
              "type": "string"
            },
            "type": [
              "object",
              "null"
            ]
          },
          "json": true,
          "links": true,
          "media": true,
          "message": {
            "type": [
              "string",
              "null"
            ]
          },
          "ok": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "parse_error": {
            "type": [
              "string",
              "null"
            ]
          },
          "redirect_chain": {
            "items": {
              "type": "string"
            },
            "type": [
              "array",
              "null"
            ]
          },
          "response_format": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "format": "uint16",
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          },
          "status_text": {
            "type": [
              "string",
              "null"
            ]
          },
          "transformed": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "title": "FetchResponse",
        "type": "object"
      }
    },
    {
      "description": "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.",
      "metadata": {
        "internal": true
      },
      "name": "web::inject-guidance",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "GenerateContext": {
            "properties": {
              "system_prompt": {
                "default": "",
                "description": "The system prompt assembled so far (base + any prior hook's mutation).",
                "type": "string"
              }
            },
            "type": "object"
          }
        },
        "description": "The slice of the `pre_generate` hook envelope we read (lenient: ignores every other field the harness sends). The harness nests the live generation context under `generate` (see harness `HookRunner::run_pre_generate`).",
        "properties": {
          "generate": {
            "$ref": "#/definitions/GenerateContext"
          }
        },
        "title": "PreGenerateEvent",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "PreGenerateMutations": {
            "description": "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.",
            "properties": {
              "system_prompt": {
                "description": "Full replacement system prompt (base + appended guidance). The harness overwrites, it does not merge.",
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "type": "object"
          }
        },
        "description": "Hook envelope returned to the harness: the mutations to apply to the generation.",
        "properties": {
          "mutations": {
            "$ref": "#/definitions/PreGenerateMutations"
          }
        },
        "required": [
          "mutations"
        ],
        "title": "PreGenerateResponse",
        "type": "object"
      }
    },
    {
      "description": "Internal: reload web settings from the authoritative configuration on change.",
      "metadata": {
        "internal": true
      },
      "name": "web::on-config-change",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "title": "OnConfigChangeRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "ok": {
            "type": "boolean"
          }
        },
        "required": [
          "ok"
        ],
        "title": "OnConfigChangeResponse",
        "type": "object"
      }
    }
  ],
  "triggers": []
}