Add Telegram group management planner with forum topic actions

[partyplatter08-lab]

/claim #65

Summary

• Add Lux.Integrations.Telegram.GroupManager to build and optionally execute normalized Telegram Bot API plans for member management, permission templates, moderation/spam protection, group settings, channel posts, forum topic operations, and admin audit logging.
• Add Lux.Prisms.Telegram.Group.ManageGroup so agents can dry-run or execute group/channel administration actions through the existing Telegram client.
• Document group/channel management examples and expand unit coverage across planning, validation, execution, moderation decisions, action aliases, official Bot API path mapping, audit output, and error handling.

Closes #65.

Validation

• mix format --check-formatted lib/lux/integrations/telegram/group_manager.ex lib/lux/prisms/telegram/group/manage_group.ex test/unit/lux/integrations/telegram/group_manager_test.exs test/unit/lux/prisms/telegram/group/manage_group_test.exs guides/telegram.livemd
• mix credo --strict lib/lux/integrations/telegram/group_manager.ex lib/lux/prisms/telegram/group/manage_group.ex test/unit/lux/integrations/telegram/group_manager_test.exs test/unit/lux/prisms/telegram/group/manage_group_test.exs
• MIX_ENV=test mix test.unit test/unit/lux/integrations/telegram/group_manager_test.exs test/unit/lux/prisms/telegram/group/manage_group_test.exs
• MIX_ENV=test mix test.unit test/unit/lux/integrations/telegram test/unit/lux/prisms/telegram
• MIX_ENV=test mix coveralls.detail --include unit test/unit/lux/integrations/telegram/group_manager_test.exs test/unit/lux/prisms/telegram/group/manage_group_test.exs (GroupManager 93.4%, ManageGroup 100.0%)
• MIX_ENV=test mix coveralls --include unit --max-cases 1

[MyTH-zyxeon]

Nice scope coverage here. I walked through the diff against #65 and found a few acceptance-risk items that seem worth tightening before review:

1. ManageGroup declares action and category as strings in output_schema, but the handler returns the raw GroupManager plan with atom values like :restrict_member / :member_management, and the tests assert those atoms. If agents or schema validators consume the prism output, this can fail even when planning succeeds. I would normalize those fields to strings at the prism boundary or update the schema/tests to match the actual contract.

2. Ordinary admin actions build an audit_entry, but they do not append a log-delivery request when log_chat_id is present. Only moderate_message and log_admin_action call audit_log_requests/3, so ban_member, set_permissions, channel actions, forum-topic actions, etc. can execute without sending an admin log despite the bounty calling for an admin logging system. A regression test for log_chat_id on a normal member-management action would make this visible.

3. The spam-protection path is still mostly caller-provided heuristics: max_recent_messages depends on an external recent_message_count, and there is no per-chat/user window, duplicate-message/link history, or injectable state adapter. That may be fine as a planner, but the acceptance criteria read like the module should either own the rate/spam state boundary or document and test the required callback/input contract.

4. The permission system is strong on templates, but execution does not appear to offer a preflight check that the bot actually has the relevant admin rights before sending actions such as restrict/ban/promote/tag management. Even a dry-run/preflight helper that maps actions to required Telegram rights would make permission failures much easier for agents to reason about before live execution.

These are all small, bounded follow-ups and would make the PR more clearly satisfy the permission, moderation, logging, and spam-protection acceptance criteria in #65.

[partyplatter08-lab]

Thank you! I will take a look at those and have it ready shortly.

[partyplatter08-lab]

Here are the changes that fix what you mentioned. If there is anything else I missed just let me know.

[MyTH-zyxeon]

Follow-up after rechecking this PR at 933984c1ca100783e3ad8d376c8e03b6906ec9d7: thanks for addressing the earlier schema/logging/spam-window points. The updated plan is much closer. I see a few remaining review risks that are worth tightening before maintainers evaluate #65:

1. The execution auth contract is still implicit. ManageGroup.handler/2 passes token through take_params/2, and the execution test uses token: "test-token", but token is not advertised in the prism input schema or guide. If production execution depends on configured client auth instead, the guide should say that; otherwise agents have no documented way to execute real Telegram requests.
2. Destructive execute: true operations can run with bot_admin_rights absent because preflight only blocks when rights are explicitly configured and failing. For ban/restrict/delete/promote paths, I would either require bot_admin_rights before execution or return a stronger warning/error state so dry-run safety does not disappear in live mode.
3. The acceptance criteria say member management should cover add/remove/restrict. Telegram Bot API can model remove/restrict directly, but "add" usually needs invite-link or join-request approval semantics. The PR has invite-link and approve/decline join-request actions; a short doc/test mapping "add member" to those supported Bot API workflows would prevent scope ambiguity.
4. Performance optimization is still mostly asserted by structure. A small stress/unit test around large recent_messages windows and bulk delete validation would give reviewers concrete evidence for the performance criterion without needing a live bot.

These are narrow follow-ups: they keep the improved planner intact while making execution safety and acceptance-criteria mapping easier to verify.

[MyTH-zyxeon]

Follow-up2 review assist for #65 / #611 after rechecking 933984c1ca100783e3ad8d376c8e03b6906ec9d7. No new commit appeared after the prior follow-up, so I kept this to a separate acceptance checklist instead of repeating the same points:

1. ManageGroup.output_schema still does not advertise several high-value fields returned by normalize_output/1, including preflight, violations, moderation_action, and results. Those are the fields agents would need to decide whether a moderation plan is safe to execute and why a message was flagged. I would add them to the schema and keep the existing prism schema test asserting they stay present.

2. GroupManager.execute/2 maps every request even after an earlier request fails. For multi-request plans such as delete + restrict/ban + audit log, that can leave a partial execution trail where a later audit message is sent even though the destructive moderation request failed. A safer contract would either short-circuit after the first failed request or make the audit log include per-request success/failure so the admin channel cannot imply that the primary action succeeded.

3. Sticker-set actions are preflighted only with can_change_info, but Telegram also exposes can_set_sticker_set through getChat as a runtime capability for sticker-set management. If Telegram Group Management ($1,800) #65 expects reliable group settings coverage, it would be worth documenting this limitation or adding a separate capability warning/test for set_sticker_set / delete_sticker_set so agents know those actions may need a getChat capability check before live execution.

These are not blockers to the overall direction; the PR already covers a lot of the requested surface. They are the remaining places I would expect maintainers to probe before accepting the bounty.

[partyplatter08-lab]

Sorry I was inactive for most of today. I will work on those then do a deeper check just to make sure as well. Sorry for any inconvenience. I will reach out when done.

[partyplatter08-lab]

Follow-up on the remaining #65 review risks is now in a641b53.

Addressed:

• ManageGroup.output_schema now advertises the normalized fields agents consume (preflight, violations, moderation_action, results, etc.), with schema regression coverage.
• GroupManager.execute/2 now stops after the first failed request, so a multi-request moderation plan will not send an audit log after a failed destructive request; the all-success audit path remains covered.
• Sticker-set actions now surface a can_set_sticker_set capability warning, with tests and guide notes.
• The guide documents execution auth/token behavior, bot_admin_rights, allow_unverified_admin_rights, and the add-member mapping through invite links / join-request approval.
• Added coverage for large recent_messages windows / moderation performance expectations.

I also checked the branch against the latest review checklist. I could not rerun mix in this container because Elixir/Mix is not installed here, so I am not claiming a fresh local run beyond the validation already in the PR body. Happy to tighten anything else reviewers spot.

[partyplatter08-lab]

Follow-up verification update: I was able to run the focused Telegram group-management test suite in Docker, using the repo-relative test.envrc and installing Node in the Elixir image for the NodeJS supervisor.

Command shape:

docker run --rm -v /home/lando/bounty-hunter/Spectral-Finance-lux:/repo -w /repo/lux -e MIX_ENV=test elixir:1.18.1 bash -lc 'apt-get update >/tmp/apt-update.log && apt-get install -y nodejs npm >/tmp/apt-install.log && mix local.hex --force >/tmp/hex.log && mix local.rebar --force >/tmp/rebar.log && mix deps.get >/tmp/deps.log && mix test --include unit test/unit/lux/prisms/telegram/group/manage_group_test.exs'

Result:

Running ExUnit with seed: 549174, max_cases: 8
Excluding tags: [:skip, :integration]
Including tags: [:unit]

Finished in 0.2 seconds (0.2s async, 0.00s sync)
9 tests, 0 failures

This covers the ManageGroup prism/schema/execution-safety tests added for the remaining #65 review risks. The run produced only pre-existing compile warnings in unrelated modules (allora/get_topics, allora/get_inference, mira).