feat(ai): gist report with call flow and etherscan hyperlinks

[spalen0]

What

The AI explanation gist was just the raw LLM detail. It now publishes a structured report — metadata header, the Telegram summary, a deterministic call flow, and the analysis.

Example output

Before	https://gist.wavey.info/ZtoYmJ5CG6TvziTDhuiSuhQz
After	https://gist.wavey.info/BJvmyq789oM6imwWOxvRFJDx

Both are the same Infinifi addFarms(uint256,address[]) timelock operation, generated by the real pipeline (live Etherscan labels + LLM).

Changes

• New utils/llm/report.py — builds the gist page. The call flow comes straight from the decoded calldata (per-call target, signature, ABI parameter names, ETH value, nested bytes payloads unwrapped) rather than being asked of the LLM, so it can't be hallucinated, re-ordered, or summarized away. Every address is rendered full-length (per the repo's "no truncated addresses" rule) as a link to the chain's explorer, annotated with its contract label / token symbol.
• Addresses are always hyperlinked in the analysis — _build_prompt now emits an --- Address Links --- section containing the exact markdown for each address in the transaction, and the system prompt requires the detail to use it. The model copies a line instead of assembling an explorer URL or guessing which explorer a chain uses. The TLDR stays plain text, since it goes to Telegram unchanged.
• Contract header links to Etherscan via ReportContext.label_address, defaulting to the executing timelock/Safe. Safe multisend batches label the utility contract instead, so _explain_safe_tx() passes the outer target in that path.
• Gist titles go from a constant AI Transaction Analysis to <contract> - <DD/MM/YYYY HH:MM> - <RISK> (UTC), e.g. Infinifi Shorttimelock - 11/08/2026 10:04 - LOW, so a list of reports is scannable. Falls back to protocol name, then the old constant.

Bugs found while validating live

• _marker_pattern matched "Detail" inside a ## Detailed Analysis heading, slicing the published report down to ed Analysis — visible at the top of the "before" gist above. Fixed with a word-boundary lookahead.
• A leading "Detailed Analysis" heading in the LLM output now gets stripped so it doesn't double up with the report's own ## Analysis.

Refactor

looks_like_calldata / try_decode_inner_calldata / MAX_BYTES_RECURSION_DEPTH moved from ai_explainer.py to utils/calldata/decoder.py (their natural home) so report.py can share them without a circular import. collect_unique_addresses extracted so the label lookup and the links block cover exactly the same address set.

Testing

• New tests/test_llm_report.py (25 cases) plus explainer-side coverage for the links section, address collection, title, and the marker-regex fix.
• uv run ruff format . / uv run ruff check . clean, uv run mypy clean for the touched files.
• uv run pytest tests/ → 752 passed, 0 failed. A second commit fixes test_monitoring_tasks_exist_in_jobs_yaml, which was already failing on main: the hourly maple job was disabled in jobs.yaml (71c02bb) but monitoring.yaml still listed protocols/maple/main.py as scheduled. Marked the entry disabled: true, following the euler/pendle/silo convention (shared Safe/timelock monitors stay listed).
• Validated end-to-end against the live Infinifi transaction, including the published gists linked above.

🤖 Generated with Claude Code

[spalen0]

[P2] Handle addresses inside tuple parameters — utils/llm/report.py:152

Confirmed and fixed in 0df1c72.

Reproduced first — _parse_param_types does support tuples, so (address,uint256) arrives as a real param and hit the scalar fallback:

- `(address,uint256)`: `('0x79e1b8e45932a7c802ea3dab3844e5dea68d971f', 5)`
addresses collected: ['0xF5f2718708f471e43968271956CC01aaA8c46119']   ← struct address missing

The second half was the more damaging one: _extract_address_args didn't walk tuples either, so the address never reached the label lookup or the Address Links block, and the LLM had no link to copy for it in the prose.

Now:

- `(address,address,uint256)`:
  - `address`: [`0x79e1B8e45932A7C802eA3dAb3844e5DEa68d971f`](https://etherscan.io/address/0x79e1B8e45932A7C802eA3dAb3844e5DEa68d971f)
  - `address`: [`0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`](https://etherscan.io/address/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48)
  - `uint256`: `860,000,000,000,000,000`

• Arrays and tuples are decomposed recursively via array_element_type / tuple_component_types, covering arrays of structs ([0], [1] index bullets) and nested tuples.
• iter_address_values() walks the same type structure and is shared with _extract_address_args, so rendering and collection can't drift apart.
• Plain address[] keeps its compact index-free bullets — no output churn for the common case.
• Arity mismatch between a tuple type and its value falls back to the scalar render rather than raising.
• decoder._split_top_level is now public split_top_level_types so the report decomposes tuple types with the same parser instead of a second implementation.

8 new tests in tests/test_llm_report.py::TestCompositeParams plus a collection-side case in test_ai_explainer.py. Full suite: 760 passed.

One related gap left deliberately out of scope: _format_decoded_calls (the prompt's Decoded Calldata section, pre-existing on main) still prints tuples raw. That section is accurate, just unannotated, and the LLM now gets the nested addresses via Address Links — happy to do it as a follow-up if you'd rather it match.