feat: chats inspect (CLI/HTTP/MCP) and chats set-ttl (CLI)

[popstas]

Adds a new chats/ domain area with two operations that had no equivalent before: a read-only chats inspect on all three surfaces, and a CLI-only chats set-ttl that writes a chat's auto-delete period.

folders inspect returns two fields per chat by design and groups get-layout reads one boolean — nothing could report a chat's TTL, description, member counts, restrictions or our own admin rights, and nothing could change the TTL at all.

Surfaces

Command	CLI	HTTP	MCP
chats inspect	✅	GET /telegram/chats/inspect	telegram_chats_inspect
chats set-ttl	✅	— (deliberate)	— (deliberate)

telegram-assistant chats inspect (--chat-id N | --chat-name TITLE | --entity REF) [--folder-name NAME] [--folder-id N] [--raw]
telegram-assistant chats set-ttl (--chat-id N | --chat-name TITLE | --entity REF) --ttl off|<duration> [--folder-name NAME] [--folder-id N] [--dry-run]

Both remote inspect surfaces call one shared helper, inspect_chat_for_request, so parameter names, error mapping and payload agree by construction rather than by coincidence. set-ttl is CLI-only by explicit request; the domain layer stays surface-agnostic, so adding HTTP/MCP later is wiring, not redesign.

Architecture

src/telegram_assistant/chats/ follows the members/ split — one operation per file, READ and WRITE never mixed:

• service.py — ChatInfo (frozen, ~70 fields, to_dict()), the ChatInspectBackend protocol, inspect_chat(). READ-gated before any Telegram call. No telethon import.
• ttl.py — parse_ttl(), ChatTtlBackend, SetTtlRequest/SetTtlResult, set_chat_ttl(). WRITE-gated. No operation row and no idempotency key — a single-step write against a naturally idempotent target, shaped like notifications mute.
• telethon_backend.py — TelethonChatInspectBackend (resolve the peer once, one GetFull*, map the pair — two RPCs maximum, no dialog walk) and TelethonChatTtlBackend below it.
• http_api/chats.py — the route, chat_inspect_backend_factory on app.state (returns None → 503 until the client connects), and the shared request helper.

The inspect payload is flat and kind-agnostic: None where a field does not apply, so jq .ttl_period works regardless of what was inspected.

chats set-ttl

The gap was found the hard way: disabling auto-delete across a 78-chat folder needed an ad-hoc messages.SetHistoryTTL script, bypassing telegram.access, --dry-run and any pacing. That run produced three facts the design is built on, none of them guessable from the API docs — they're why this is not a thin RPC wrapper:

1. Every successful set posts a service message into the chat, visible to all members — including a set that changes nothing. So set_chat_ttl reads the current period first and short-circuits when it already matches (changed: false, no write). That is a correctness requirement, not an optimization: without it, re-running over a folder spams every chat in it.
2. The RPC's return value cannot be trusted. One chat failed with Telethon's TypeNotFoundError (constructor newer than the installed layer) — yet the write had applied. So the adapter treats TypeNotFoundError during the write as non-fatal and falls through to an unconditional read-back, which is the authoritative ttl_period. A read-back disagreeing with the request is an error naming both values, never a reported success.
3. SetHistoryTTL is flood-waited hard, and the waits escalate — 261s, 703s, 866s observed on one account within an hour. The write goes through the shared Pacer on its own gate key ttl:<bare id> (not shared with the pin gate — different Telegram limits), with three new telegram.* config keys: ttl_min_interval_seconds (2.0), ttl_max_flood_wait_seconds (3600, high enough to sit through the observed waits but finite), ttl_max_flood_wait_retries (5, since the pacer's default 3 is too few when waits escalate).

--ttl takes off/0, <int><unit> (s/m/h/d/w) or a bare integer of seconds; negatives, non-integers, unknown units and anything past 2**31 - 1 are rejected at parse time with exit 2. There is deliberately no allow-list of preset durations — Telegram's clients offer day/week/month, but live chats were found at 31, 93 and 180 days. The server is the authority.

previous_ttl_seconds / ttl_period are null when auto-delete is off, never 0, matching what chats inspect reports for the same chat.

Deliberate decisions

• raw is CLI-only. HTTP and MCP accept the parameter and reject it (400 / tool error) rather than ignoring it — a silently dropped raw=true would look like an empty raw payload. The raw dump carries considerably more than the curated set: a legacy group's whole member roster, a user's business_location, stories, personal_channel_id.
• access_hash never appears in any payload, including --raw. Redaction is recursive.
• FloodWaitError is mapped on inspect, unlike members list which lets it fall through: HTTP 502 with Retry-After and retry_after_seconds, MCP needs_review with the same field.
• Reference set matches the CLI on every surface — entity, chat_id, or chat_name with folder_name/folder_id — rather than the narrower pair members list uses.
• set-ttl needs only WRITE. write does not imply read in this project's policy, and the get_ttl calls are part of the write operation, not a separate READ grant.
• No folder-wide sweep for either command — the caller loops over chats, as with members list --user.

Defects caught by review, not by the tests

1. access_hash leaked through raw.full.chat_photo.access_hash on every peer kind — _serialize() stripped only the top level. Found during live verification; the unit fakes are flat and carry no nested objects. Fixed with a recursive _redact() plus tests asserting against the whole serialized payload.
2. muted was wrong in three of five real states, including after this project's own notifications unmute (which writes mute_until=0, decoded by telethon 1.44 as a non-null 1970 date). muted is now true only while a mute is in force, muted_until is None for a past timestamp, and silent became its own field.
3. A flood-wait raised during reference resolution escaped un-annotated, so the half of the inspect surface where FLOOD_WAIT is most likely returned a 502 with no Retry-After — contradicting the docs added in the same change.
4. The spec's required flood-wait WARNING was never implemented. Pacer.run now logs before every retry sleep, naming the key, pause and attempt — a 15-minute silent sleep was indistinguishable from a hang. It goes to stderr (verified), so it cannot pollute the JSON stdout payload, and messages pin/unpin get it too since they share the pacer.

Tests

2435 passing, ruff clean. test_chats_inspect.py, test_chats_inspect_backend.py (all peer kinds), test_cli_chats_inspect.py, test_chats_inspect_surfaces.py (HTTP + MCP, full status ladder on both reference branches), test_chats_set_ttl.py (gate-before-RPC, no-op short-circuit, dry-run, read-back wins, mismatch raises, TypeNotFoundError tolerance), test_chats_set_ttl_backend.py, test_cli_chats_set_ttl.py.

Manual verification checklist

• chats inspect --entity <supergroup> — ttl_period matches what the Telegram client shows under auto-delete
• chats inspect --entity me — kind: user, no crash on group-only fields
• chats inspect --entity <channel> --raw | grep -c access_hash → 0
• topics_layout agrees with groups get-layout on the same forum supergroup
• curl "$API/telegram/chats/inspect?entity=me" with a bearer token → same fields as the CLI
• curl "$API/telegram/chats/inspect?entity=me&raw=true" → 400 naming the reason
• MCP telegram_chats_inspect through the inspector → same payload as HTTP
• A chat with no read grant in telegram.access → CLI exit 3, HTTP 403, MCP access-denied
• chats set-ttl --entity me --ttl 1d --dry-run → reports the change, writes nothing
• chats set-ttl --entity me --ttl 1d → changed: true, chats inspect --entity me agrees
• chats set-ttl --entity me --ttl off twice — the second run is changed: false and posts no service message
• chats set-ttl on a chat with no write grant → exit 3

(set-ttl checks are mutating; run them against Saved Messages only, per the project's e2e rule.)

Known gaps

• The bot and basic_group inspect branches were never exercised against the live account — no such chats were reachable. Covered by unit tests plus an offline run of real telethon 1.44 objects through the backend.
• chats set-ttl has had no live run on this branch; the behaviour it encodes comes from the ad-hoc 78-chat run that motivated it.
• If _shallow_for finds no id match among 2+ entries (a channel plus its linked discussion group), kind still reports supergroup because broadcast is read off the absent object.
• The set-ttl payload's chat_name echoes the caller's own reference string, not the chat's real title (documented in SKILL.md).
• Datetimes render differently on the wire: the CLI's default=str gives 2026-01-02 03:04:05+00:00, the JSON surfaces give ISO-8601. Documented, not normalized.

🤖 Generated with Claude Code