[chaliy]

Requested by Михайло · project thread

What changed

New opt-in tool feature exposes markkit::tool::MarkkitTool, an LLM agent tool with the same shape as bashkit's tool module (Everruns toolkit-library contract):

MarkkitToolBuilder → MarkkitTool (metadata, schemas) → single-use ToolExecution → ToolOutput.

• Builder: locale (en-US/uk-UA), config(MarkkitBuilder), allow_url, max_output_chars (default 100 000); build_tool_definition() (OpenAI JSON), build_service() (tower::Service), build_input_schema()/build_output_schema().
• One call = one document: exactly one of url, html, content_base64 (+ file_name/content_type hints), optional max_chars.
• Result: {markdown, title, format, warnings, truncated}; metadata carries stats and length.
• Errors: extraction/validation failures are UserFacing (safe for the model, localized prefix); I/O is Internal.
• Also adds Markkit::extract_url_document (URL extraction with format/title/warnings/stats); extract_url now delegates to it.
• New knowledge concept integrations/tool-contract.md; tool args added to the threat-model attack surface; example examples/agent_tool.rs runs in CI and just examples.

Feature is off by default (unlike bashkit) so plain library users don't pull tower.

Why

Roadmap initiative 8: agent tool (MCP server optional, later). Follow-ups: WASM package, Node options parity.

Before / After

Before: no tool layer; hosts hand-write schemas and wrappers.

After (cargo run -p markkit --features tool --example agent_tool):

markkit: converts web pages and documents to Markdown. Pass one of url, html, content_base64. Use max_chars to limit output.

{
  "format": "html",
  "markdown": "# Release notes\n\n- Agent tool\n- WASM\n",
  "title": null,
  "truncated": false,
  "warnings": []
}

Risk

• Low: additive, behind a non-default feature. extract_url refactor keeps the same hint (response content type).
• Security: tool args are untrusted. Validated before execution; base64 length bounded before decode; url goes through the existing SSRF guard (tested via the tool) and can be disabled; output capped.

Checklist

• Tests added or updated (20 unit tests in tool::tests: metadata/locale, schema gating, sources, truncation, validation negatives, SSRF, error mapping, stream, service)
• Backward compatibility considered