omnius 1.0.591 → 1.0.592

package/docs/telegram-reflection-corpus-integration-plan.md

@@ -0,0 +1,306 @@
+# Telegram Reflection Corpus Integration Plan
+
+Date: 2026-05-15
+
+Status: planning and implementation tracker
+
+Goal: make Telegram reflection cycles operate over a durable scoped corpus, not just the retained in-memory chat window. Each cycle must efficiently perform tagging, summation, titling, extraction, and linking over Telegram-scoped conversation data, then commit the resulting artifacts back into memory and graph stores so future reflection, live replies, and multimodal identity recall can use them.
+
+## Hard Requirements
+
+- No implementation stubs, placeholder functions, dead exports, or unused planning-only branches.
+- No hidden fallback to workspace filesystem dream mode from Telegram chat contexts.
+- Every artifact must be scoped by Telegram session key, chat id, chat type, and message anchors.
+- Public group reflection must stay private unless a later model-gated outreach pass chooses a safe same-group reply.
+- Private DM outreach remains disabled unless an explicit consent and delivery policy is added.
+- Graph traversal must start from scoped Telegram corpus candidates, not repo files.
+- Vector search must be used first when embeddings are available; lexical/recent fallback is allowed only when embedding generation is unavailable and must be recorded in artifact metadata.
+- Candidate selection must prefer inner graph nodes with meaningful degree and evidence, then randomly choose one candidate from the eligible set for reflection.
+- The graph walk must expand from the selected node across valid scoped edges until depth, candidate, and token budgets are met.
+- The model extraction pass must return structured data for all five required operations: tagging, summation, titling, extraction, and linking.
+- All committed memory must preserve source message ids and reply relationships.
+
+## Current State
+
+Telegram already has a scoped reflection command path:
+
+- `packages/cli/src/tui/telegram-bridge.ts:2152` has `handleTelegramReflectionSlash`.
+- `packages/cli/src/tui/telegram-bridge.ts:2710` has `runTelegramChannelDmnForSession`.
+- `packages/cli/src/tui/telegram-bridge.ts:2746` has `runTelegramChannelDmnSweep`.
+- `packages/cli/src/tui/telegram-bridge.ts:2767` has `maybeSendTelegramReflectionFollowup`.
+- `packages/cli/src/tui/telegram-bridge.ts:2877` injects the latest reflection context into live routing.
+
+The existing artifact builder is still mostly a retained-history summarizer:
+
+- `packages/cli/src/tui/telegram-channel-dmn.ts:44` defines `TelegramChannelDaydreamInput`.
+- `packages/cli/src/tui/telegram-channel-dmn.ts:57` defines `TelegramChannelDaydreamArtifact`.
+- `packages/cli/src/tui/telegram-channel-dmn.ts:516` builds the artifact.
+- `packages/cli/src/tui/telegram-channel-dmn.ts:579` formats markdown.
+- `packages/cli/src/tui/telegram-channel-dmn.ts:641` writes JSON and markdown.
+- `packages/cli/src/tui/telegram-channel-dmn.ts:666` formats injected runtime context.
+
+Telegram conversation retention exists but does not yet commit text turns into the shared graph/vector corpus:
+
+- `packages/cli/src/tui/telegram-bridge.ts:2539` computes scoped conversation file paths.
+- `packages/cli/src/tui/telegram-bridge.ts:2556` loads persisted chat history.
+- `packages/cli/src/tui/telegram-bridge.ts:2623` saves chat history, participants, memory cards, stimulation, and reflection state.
+- `packages/cli/src/tui/telegram-bridge.ts:2901` records user messages in scoped history.
+- `packages/cli/src/tui/telegram-bridge.ts:2949` records assistant messages in scoped history.
+- `packages/cli/src/tui/telegram-bridge.ts:3216` updates JSON-only memory cards.
+- `packages/cli/src/tui/telegram-bridge.ts:3322` builds the live Telegram context stream.
+
+Shared memory primitives already exist:
+
+- `packages/memory/src/episodeStore.ts:66` includes `social`, `text`, and `reflection` modalities.
+- `packages/memory/src/episodeStore.ts:355` inserts episodes and auto-links them when a graph is attached.
+- `packages/memory/src/episodeStore.ts:412` performs lexical plus vector search.
+- `packages/memory/src/episodeStore.ts:545` merges PPR graph retrieval with normal search.
+- `packages/memory/src/episodeStore.ts:625` stores native embeddings.
+- `packages/memory/src/episodeStore.ts:631` stores CLIP-compatible embeddings.
+- `packages/memory/src/temporalGraph.ts:24` includes Telegram-relevant relations such as `contains`, `authored_by`, `said_by`, `replied_to`, `depicts`, `named_as`, `voice_sample_of`, and `same_person_candidate`.
+- `packages/memory/src/temporalGraph.ts:121` creates graph nodes.
+- `packages/memory/src/temporalGraph.ts:186` creates graph edges.
+- `packages/memory/src/temporalGraph.ts:253` returns valid one-hop neighbors.
+- `packages/memory/src/zettelkasten.ts:94` finds vector/CLIP neighbors.
+- `packages/memory/src/zettelkasten.ts:127` links related episodes into the graph.
+- `packages/memory/src/pprRetrieval.ts:161` runs personalized PageRank.
+- `packages/memory/src/pprRetrieval.ts:252` maps PPR graph scores back to episodes.
+- `packages/memory/src/multimodalIdentity.ts:178` ingests multimodal evidence into episodes and graph nodes.
+
+## Target Architecture
+
+### Corpus Layer
+
+Add `packages/cli/src/tui/telegram-reflection-corpus.ts`.
+
+Responsibilities:
+
+- Convert scoped Telegram history entries into durable `EpisodeStore` episodes.
+- Use `MultimodalIdentityService` for message, sender, reply, and media graph atoms where the message has Telegram evidence.
+- Generate text embeddings for new or missing scoped Telegram text/reflection episodes when an embedding backend is configured.
+- Add graph nodes and edges that make text-only Telegram turns traversable even without media:
+  - scope node contains message node
+  - message node authored_by sender node
+  - assistant/user message node replied_to target message node when present
+  - message node said_by sender node for natural-language content
+  - message node related_to derived tag/title/summary nodes after extraction
+- Expose a single integrated function for the reflection runner:
+  - `buildTelegramReflectionCorpus(options): Promise<TelegramReflectionCorpusResult>`
+
+Required result shape:
+
+- `stats`: counts for retained messages, inserted episodes, reused episodes, embedded episodes, candidate episodes, graph nodes, graph edges, selected nodes, walked episodes.
+- `seed`: selected episode id, node id, node text, selection method, vector search limit used, graph depth used.
+- `walk`: ordered nodes, edges, episodes, source message ids, reply message ids.
+- `fallbacks`: explicit list of degraded paths such as embedding unavailable or no inner graph candidates found.
+
+### Graph/Vector Selection Layer
+
+Add `packages/memory/src/graphWalk.ts` and export it from `packages/memory/src/index.ts`.
+
+Responsibilities:
+
+- Accept a list of vector/lexical episode candidates plus a `TemporalGraph`.
+- Resolve candidate episodes to graph nodes through current edges carrying `sourceEpisodeId`.
+- Score inner node candidates by:
+  - valid degree;
+  - distinct source episode count;
+  - relation diversity;
+  - scoped Telegram metadata match;
+  - recency of source evidence.
+- Expand candidate search limits in order: 48, 96, 192, 384, 500 until at least one eligible inner node exists or the corpus is exhausted.
+- Randomly choose one eligible inner node using a deterministic seeded RNG derived from session key plus artifact run id.
+- Walk outward breadth-first from the selected node across valid graph edges.
+- Return the selected seed, visited nodes, traversed edges, source episode ids, and degree/evidence diagnostics.
+
+Exact memory anchors:
+
+- `packages/memory/src/temporalGraph.ts:253` currently provides only one-hop neighbors; `graphWalk.ts` will compose this without changing graph storage.
+- `packages/memory/src/pprRetrieval.ts:161` remains available for PPR scoring, but this reflection cycle needs explicit node candidate selection, seeded random choice, and bounded walk diagnostics.
+- `packages/memory/src/index.ts:74` currently exports PPR helpers; add graph walk exports adjacent to this section.
+
+### Extraction Layer
+
+Add `packages/cli/src/tui/telegram-reflection-extraction.ts`.
+
+Responsibilities:
+
+- Build a compact corpus packet from the graph walk and source episodes.
+- Ask the configured backend for strict JSON output.
+- Validate and normalize the parsed structure without regex-based semantic decisions.
+- Return all five required operation groups:
+  - `tagging`: scoped tags with confidence, source message ids, and target node/episode ids.
+  - `summation`: concise channel/thread/user/message-window summaries with evidence anchors.
+  - `titling`: artifact title, thread titles, memory card titles, and graph node labels.
+  - `extraction`: facts, preferences, open questions, decisions, identity assertion candidates, media references, and follow-up opportunities.
+  - `linking`: proposed graph links between messages, users, topics, media, summaries, and prior memory cards.
+- Never claim a face, voice, or person identity unless the source corpus contains explicit identity evidence or the `identity_memory` tool later verifies it.
+
+Required schema:
+
+- `artifact_title: string`
+- `tags: Array<{ label, kind, confidence, source_message_ids, target_episode_ids, target_node_ids }>`
+- `summaries: Array<{ title, scope, text, confidence, source_message_ids, target_episode_ids }>`
+- `extractions: Array<{ kind, text, confidence, source_message_ids, target_episode_ids, target_node_ids }>`
+- `links: Array<{ relation, src_node_text, dst_node_text, confidence, fact, source_message_ids, target_episode_ids }>`
+- `followups: Array<{ target, text, reply_to_message_id, rationale, confidence }>`
+
+### Artifact Layer
+
+Extend `packages/cli/src/tui/telegram-channel-dmn.ts`.
+
+Required changes:
+
+- Bump artifact `version` from `2` to `3`.
+- Add `corpus`, `selectedSeed`, `graphWalk`, `tagging`, `summation`, `titling`, `extraction`, and `linking` fields to `TelegramChannelDaydreamArtifact`.
+- Keep existing fields only when they are either directly useful to live routing or backed by corpus extraction.
+- Update `buildTelegramChannelDaydream` to accept an optional corpus/extraction result and merge it into the artifact.
+- Update markdown formatting at `packages/cli/src/tui/telegram-channel-dmn.ts:579` to show source anchors, graph seed, walk stats, tags, summaries, titles, extractions, and links.
+- Update injected context at `packages/cli/src/tui/telegram-channel-dmn.ts:666` to prioritize:
+  - selected seed;
+  - graph walk summary;
+  - top tags;
+  - strongest summaries;
+  - unresolved extraction items;
+  - reply-linked source message ids.
+
+### Telegram Bridge Wiring
+
+Modify `packages/cli/src/tui/telegram-bridge.ts`.
+
+Required changes:
+
+- At `recordTelegramUserMessage` (`packages/cli/src/tui/telegram-bridge.ts:2901`), enqueue or immediately upsert the text turn into the scoped reflection corpus after local history is recorded.
+- At `recordTelegramAssistantMessage` (`packages/cli/src/tui/telegram-bridge.ts:2949`), upsert assistant outputs into the same corpus with assistant sender metadata and reply anchors.
+- At `runTelegramChannelDmnForSession` (`packages/cli/src/tui/telegram-bridge.ts:2710`), build the corpus first, run graph/vector selection, run extraction, then build and write the artifact.
+- At `maybeSendTelegramReflectionFollowup` (`packages/cli/src/tui/telegram-bridge.ts:2767`), source `candidateMessageIds` from artifact extraction/linking/source anchors, not only curiosity threads and memory proposals.
+- At `handleTelegramReflectionSlash`, expose status lines for corpus episode count, selected seed, walk size, tags, summaries, extraction count, and link count.
+- Preserve current `/reflect`, `/reflection`, `/daydream`, and Telegram-scoped `/dream` behavior; do not route these into TUI DreamEngine.
+
+### Persistence And Indexing
+
+Use existing shared stores:
+
+- `episodes.db` for text, social, and reflection episodes.
+- `knowledge.db` for graph nodes and edges.
+- `.omnius/telegram-daydreams/<session-hash>/` for JSON and markdown reflection artifacts.
+- `.omnius/telegram-conversations/<session-hash>.json` remains the lightweight retained context cache.
+
+Required data model conventions:
+
+- Episode `sessionId` is the Telegram `sessionKey`.
+- Episode `metadata.sourceSurface` is `telegram`.
+- Episode `metadata.scope` contains `{ kind: "group" | "private", id: chatId, title }`.
+- Episode `metadata.telegram` contains chat id, chat type, chat title, message id, thread id, sender id, username, display name, reply target, and media summary.
+- Graph scope node text matches `scope:telegram:<chatType>:<chatId>`.
+- Graph message node text uses a stable Telegram message key.
+- Summary/tag/title/extraction nodes must carry `sourceEpisodeId` on their creating edges.
+
+### Zettelkasten And Multimodal Memory Integration
+
+Required changes:
+
+- Text Telegram episodes with embeddings must use existing zettelkasten linking through `EpisodeStore.insert` plus explicit post-embedding link refresh.
+- CLIP-only visual/audio episodes already link through `packages/memory/src/zettelkasten.ts:94`; reflection cycles must include related visual/audio episodes when graph walk reaches media nodes.
+- `packages/memory/src/multimodalIdentity.ts:178` remains the central ingest service for media and explicit identity evidence.
+- Reflection extraction can propose identity assertion candidates, but must not commit `named_as`, `depicts`, or `voice_sample_of` unless the underlying message already contains explicit user-supplied identity evidence or a later tool call verifies it.
+
+### Efficient Small-Context Handling
+
+The reflection cycle must not dump entire chat history into the model.
+
+Budgeting rules:
+
+- Vector/lexical search candidate budget starts at 48 and expands only if no inner graph candidates are found.
+- Graph walk depth defaults to 2, expands to 3 only if fewer than 8 source episodes are recovered.
+- Corpus packet passed to extraction includes compact episode snippets, source anchors, and graph relation facts, not raw full logs.
+- Summaries and tags are committed as artifacts so future cycles can read compressed memories instead of rereading old turns.
+- Live Telegram context injection displays only top-scoring structured outputs and source anchors.
+
+## Implementation Checklist
+
+### Planning
+
+- [x] Create this tracking document before code changes.
+- [x] Confirm all existing reflection/dream tests still represent Telegram-scoped behavior.
+
+### Shared Graph Walk
+
+- [x] Add `packages/memory/src/graphWalk.ts`.
+- [x] Export graph walk helpers from `packages/memory/src/index.ts`.
+- [x] Add tests for vector candidate expansion, inner node selection, seeded random choice, scoped filtering, and bounded graph walking.
+
+### Telegram Corpus
+
+- [x] Add `packages/cli/src/tui/telegram-reflection-corpus.ts`.
+- [x] Upsert scoped Telegram user messages into `EpisodeStore`.
+- [x] Upsert scoped Telegram assistant messages into `EpisodeStore`.
+- [x] Preserve reply relationships in graph edges.
+- [x] Generate or fill text embeddings when configured.
+- [x] Refresh zettelkasten links after embeddings are stored.
+- [x] Include scoped visual/audio/media graph neighbors in walks.
+
+### Extraction
+
+- [x] Add `packages/cli/src/tui/telegram-reflection-extraction.ts`.
+- [x] Build strict JSON extraction prompt with source anchors.
+- [x] Validate tagging, summation, titling, extraction, and linking groups.
+- [x] Commit summary/tag/title/extraction episodes and graph nodes.
+- [x] Add tests for malformed JSON, empty corpus, embedding-disabled fallback, and complete five-operation output.
+
+### Artifact
+
+- [x] Bump Telegram daydream artifact to version 3.
+- [x] Add corpus, seed, walk, tags, summaries, titles, extractions, and links to the artifact.
+- [x] Update markdown output to make source anchors readable.
+- [x] Update runtime context injection to use structured reflection data.
+
+### Bridge
+
+- [x] Wire corpus upsert into `recordTelegramUserMessage`.
+- [x] Wire corpus upsert into `recordTelegramAssistantMessage`.
+- [x] Wire corpus build, graph/vector seed selection, graph walk, extraction, and artifact commit into `runTelegramChannelDmnForSession`.
+- [x] Update reflection follow-up candidate message id selection to use extraction/link anchors.
+- [x] Update `/reflect status` output with corpus and graph metrics.
+
+### Validation
+
+- [x] Run `pnpm --filter @omnius/memory test`.
+- [x] Run `pnpm --filter omnius test -- tests/telegram-bot-api-10.test.ts`.
+- [x] Add and run focused tests for the new corpus/extraction modules.
+- [x] Run `pnpm --filter @omnius/memory build`.
+- [x] Run `pnpm --filter omnius build`.
+- [x] Run `git diff --check`.
+- [x] Backward-pass each checklist item against the final diff before commit.
+
+## Backward-Pass Verification
+
+- `packages/memory/src/graphWalk.ts` implements inner-node selection from episode-backed graph evidence, seeded random choice, and bounded graph walking.
+- `packages/memory/src/temporalGraph.ts` now exposes current edges by source episode id so vector candidates can be mapped into graph neighborhoods.
+- `packages/memory/src/multimodalIdentity.ts` accepts `sessionId` and caller metadata so Telegram text/media evidence lands in the scoped episode corpus.
+- `packages/cli/src/tui/telegram-reflection-corpus.ts` upserts Telegram user and assistant turns, fills embeddings when configured, refreshes zettelkasten links, expands candidate limits, and selects graph walks.
+- `packages/cli/src/tui/telegram-reflection-extraction.ts` builds strict JSON prompts, validates all five operation groups, and commits reflection/gist episodes plus graph nodes and links.
+- `packages/cli/src/tui/telegram-channel-dmn.ts` writes version 3 artifacts with corpus, selected seed, graph walk, tags, summaries, titles, extractions, links, and follow-up candidates.
+- `packages/cli/src/tui/telegram-bridge.ts` records live Telegram turns into the corpus and routes `/reflect` through corpus build, graph walk, model extraction, artifact writing, and model-gated follow-up anchoring.
+- Regression coverage:
+  - `packages/memory/tests/graphWalk.test.ts`
+  - `packages/cli/tests/telegram-reflection-corpus.test.ts`
+  - `packages/cli/tests/telegram-reflection-extraction.test.ts`
+  - `packages/cli/tests/telegram-bot-api-10.test.ts`
+
+## Completion Definition
+
+This integration is complete only when a Telegram `/reflect` run can:
+
+1. Read the scoped chat corpus.
+2. Persist new text turns into `episodes.db`.
+3. Preserve sender, message, reply, scope, and media relationships in `knowledge.db`.
+4. Search scoped episodes with embeddings where available.
+5. Expand candidate search depth when there are not enough graph candidates.
+6. Select an inner graph node from eligible vector-search candidates.
+7. Walk the graph outward from that node within depth and token budgets.
+8. Produce structured tagging, summation, titling, extraction, and linking data.
+9. Write JSON and markdown artifacts with source message anchors.
+10. Commit reflection outputs back into episodes and graph links.
+11. Inject compact structured context into future Telegram agent turns.
+12. Let the model-gated follow-up path use the same source anchors when deciding whether to reply.

package/docs/telegram-unified-tooling-architecture.md

@@ -0,0 +1,332 @@
+# Telegram Unified Tooling Architecture
+
+Goal: give Telegram-sourced agent runs one scoped `telegram` tool that covers
+Telegram Bot API operations behind explicit Omnius policy, Telegram bot rights,
+and admin-controlled toggles. This replaces the current drift where some
+Telegram powers exist as private helpers, some exist as TUI slash commands, and
+only `telegram_send_file` is model-facing.
+
+## Current State
+
+The bot does not currently expose message deletion as an agent tool.
+
+Existing code paths:
+
+- `packages/cli/src/tui/telegram-bridge.ts`
+  - `deleteLiveMessage(...)` is a private cleanup helper for Omnius streaming
+    messages. It calls `deleteMessage`, but it is not a model-facing tool and
+    cannot be used for janitorial moderation.
+  - `deleteMessageReaction(...)` and `deleteAllMessageReactions(...)` exist as
+    bridge methods.
+  - `getChatAdministrators(...)` exists as a bridge method.
+  - `sendCallButton(...)` sends an inline URL keyboard, but the bridge does not
+    poll `callback_query` updates and does not answer callback queries.
+  - `buildSubAgentTools(...)` exposes `telegram_send_file`, not a unified
+    Telegram admin/moderation tool.
+- `packages/cli/src/tui/commands.ts`
+  - `/telegram delete-reaction ...`
+  - `/telegram delete-reactions ...`
+  - `/telegram admins ...`
+  - No `/telegram delete-message` or `/telegram delete-messages`.
+- `packages/cli/src/tui/tool-policy.ts`
+  - Whole-tool context gating exists.
+  - There is no action-level policy for one high-scope Telegram tool.
+
+Result: Omnius can send files and delete reactions, but it cannot agentically
+delete its own messages or user messages. It also cannot offer Telegram inline
+buttons for scoped tool enable/disable because callback queries are not wired.
+
+## Official API Constraints
+
+Sources:
+
+- https://core.telegram.org/bots/api#deletemessage
+- https://core.telegram.org/bots/api#deletemessages
+- https://core.telegram.org/bots/api#getchatadministrators
+- https://core.telegram.org/bots/api#callbackquery
+- https://core.telegram.org/bots/api#answercallbackquery
+- https://core.telegram.org/bots/api#inlinekeyboardmarkup
+
+Deletion constraints to model explicitly:
+
+- Bots can delete outgoing messages in private chats, groups, and supergroups.
+- Bots can delete incoming messages in private chats.
+- In groups, a bot must be an administrator to delete arbitrary messages.
+- In supergroups/channels, the bot needs `can_delete_messages` to delete
+  arbitrary messages.
+- Telegram applies message-age and service-message limits. Failed deletes must
+  report the Bot API error back to the tool result.
+- `deleteMessages` is the batch endpoint for multiple message IDs and should be
+  preferred when deleting more than one message.
+
+Inline button constraints:
+
+- The poll loop must request `callback_query` updates.
+- Every callback query should be answered with `answerCallbackQuery`, even when
+  no alert is shown, so Telegram clients stop the progress spinner.
+- Callback payloads are limited and should carry only a short signed state key
+  or compact action token, not full policy JSON.
+
+## Target Shape
+
+Expose one model-facing tool:
+
+```text
+telegram({
+  action: "...",
+  target: "...",
+  message_id: 123,
+  message_ids: [123, 124],
+  user_id: 777,
+  permissions: {...},
+  text: "...",
+  reason: "...",
+  dry_run: false
+})
+```
+
+Keep `telegram_send_file` as a compatibility alias for now, but route it through
+the same underlying delivery ledger and policy checks.
+
+### Action Groups
+
+Read actions:
+
+- `get_me`
+- `get_chat`
+- `get_chat_member`
+- `get_chat_administrators`
+- `get_message_context`
+- `get_tool_scope`
+
+Message actions:
+
+- `send_message`
+- `edit_message_text`
+- `edit_message_caption`
+- `edit_message_reply_markup`
+- `delete_message`
+- `delete_messages`
+- `pin_message`
+- `unpin_message`
+- `unpin_all_messages`
+
+Media actions:
+
+- `send_file`
+- `send_photo`
+- `send_document`
+- `send_audio`
+- `send_voice`
+- `send_video`
+
+Moderation actions:
+
+- `ban_chat_member`
+- `unban_chat_member`
+- `restrict_chat_member`
+- `promote_chat_member`
+- `set_chat_permissions`
+- `approve_chat_join_request`
+- `decline_chat_join_request`
+
+Reaction actions:
+
+- `set_message_reaction`
+- `delete_message_reaction`
+- `delete_all_message_reactions`
+
+Bot and admin actions:
+
+- `set_my_commands`
+- `get_my_commands`
+- `set_chat_menu_button`
+- `get_chat_menu_button`
+- `set_my_description`
+- `get_my_description`
+
+Policy actions:
+
+- `scope_status`
+- `enable_action`
+- `disable_action`
+- `enable_group`
+- `disable_group`
+- `render_admin_buttons`
+
+## Scope Model
+
+The `telegram` tool should evaluate four layers before making any Bot API call.
+
+1. Telegram source context
+
+- `telegram-public`: current chat only. No janitorial or moderation actions.
+- `telegram-admin-group`: current chat only. Janitorial actions allowed only if
+  the Omnius policy enables them and the sender is the authenticated admin.
+- `telegram-admin-dm`: may target the current DM or a known prior chat from the
+  bridge target registry. Unknown numeric chat IDs are allowed only when the
+  local admin explicitly supplies them.
+
+2. Omnius action policy
+
+Add action-level policy below the current whole-tool policy:
+
+```ts
+interface TelegramToolPolicy {
+  enabledActionGroups?: Record<string, boolean>;
+  enabledActions?: Record<string, boolean>;
+  chatOverrides?: Record<string, {
+    enabledActionGroups?: Record<string, boolean>;
+    enabledActions?: Record<string, boolean>;
+  }>;
+  requireAdminForMutation?: boolean;
+  dryRunByDefault?: boolean;
+}
+```
+
+Persist this under `OmniusSettings.telegramToolPolicy`.
+
+3. Bot rights
+
+Before mutating chat state, call or cache bot rights:
+
+- `getMe` for bot id.
+- `getChatMember(chat_id, bot_id)` or `getChatAdministrators(chat_id, true)`.
+- Require `can_delete_messages` before `delete_message(s)` for supergroups and
+  channels.
+- Require matching rights for pinning, restricting, banning, promotion, and
+  permissions changes.
+
+4. Operation proof
+
+Mutating tool results should include:
+
+- `action`
+- `chat_id`
+- `message_id` or `message_ids`
+- `telegram_method`
+- `ok`
+- `bot_rights_checked`
+- `policy_scope`
+- Telegram error description if failed
+
+## Admin Buttons
+
+Add a Telegram admin control surface using inline keyboards.
+
+Command routes:
+
+- `/telegram tools` in TUI: print current policy and optionally send a Telegram
+  admin panel to the admin DM.
+- `/tools` or `/telegram_tools` in Telegram admin DM: show buttons.
+- `/telegram tools group <chat>`: show/edit policy for a group.
+
+Button behavior:
+
+- Add `callback_query` to `allowed_updates` in `pollLoop`.
+- Normalize callback updates beside messages.
+- Add `handleTelegramCallbackQuery(...)`.
+- Verify callback sender is the authenticated admin.
+- Call `answerCallbackQuery` for every callback.
+- Store button state server-side:
+  - `.omnius/telegram-tool-buttons/<nonce>.json`
+  - callback payload: `omni:v1:tool:<nonce>:<action>`
+  - short TTL, e.g. 15 minutes.
+- Toggle action groups or actions, then edit the menu message with updated
+  checkboxes.
+
+Suggested panels:
+
+- Global policy:
+  - Read
+  - Message send/edit
+  - Janitorial delete
+  - Reactions
+  - Moderation
+  - Bot profile/admin
+- Current chat override:
+  - Same groups, but scoped to one chat id.
+- Safety buttons:
+  - Dry-run by default on/off.
+  - Require admin confirmation for delete-many/moderation on/off.
+
+## Code Anchors
+
+Primary implementation anchors:
+
+- `packages/cli/src/tui/telegram-bridge.ts`
+  - Add `buildTelegramTool(context, repoRoot, chatId, msg)`.
+  - Register this tool in `buildSubAgentTools(...)`.
+  - Replace direct action helpers with shared `callTelegramApiAction(...)`.
+  - Add public bridge methods:
+    - `deleteTelegramMessage(...)`
+    - `deleteTelegramMessages(...)`
+    - `getChatMember(...)`
+    - `getBotChatRights(...)`
+    - `answerCallbackQuery(...)`
+    - `sendTelegramToolPanel(...)`
+    - `handleTelegramCallbackQuery(...)`
+  - Add `callback_query` to `allowed_updates`.
+- `packages/cli/src/tui/tool-policy.ts`
+  - Add `telegram` to safe allowlists only for read/status actions.
+  - Keep high-risk behavior inside action-level policy.
+- `packages/cli/src/tui/omnius-directory.ts`
+  - Add `telegramToolPolicy?: TelegramToolPolicy`.
+- `packages/cli/src/tui/commands.ts`
+  - Add `/telegram tools`.
+  - Add `/telegram delete-message <chat> <message_id>`.
+  - Add `/telegram delete-messages <chat> <message_id,...>`.
+- `packages/cli/src/tui/interactive.ts`
+  - Wire settings save/load and bridge policy updates.
+- `packages/cli/tests/telegram-bot-api-10.test.ts`
+  - Add coverage for message deletion, batch deletion, callback query toggles,
+    policy denials, and bot-rights denials.
+- `README.md`
+  - Document the unified `telegram` tool, policy defaults, and button controls
+    after implementation.
+
+## Default Policy Recommendation
+
+Defaults should be conservative:
+
+- `telegram-public`
+  - allow read-only context actions only.
+  - deny deletion, moderation, bot profile, and arbitrary target sends.
+- `telegram-admin-group`
+  - allow `delete_message` only for current chat when the target message is the
+    bot's own message by default.
+  - require explicit policy enablement for deleting user messages.
+  - deny moderation by default.
+- `telegram-admin-dm`
+  - allow full read and send actions.
+  - allow janitorial actions only after explicit enablement.
+  - allow moderation only after explicit enablement and bot-rights confirmation.
+
+## Implementation Checklist
+
+- [x] Add `TelegramToolPolicy` settings type and load/save plumbing.
+- [x] Add `telegram` action tool with scoped target resolution.
+- [x] Add delete single/batch message bridge methods.
+- [x] Add bot-rights introspection and cache.
+- [x] Register `telegram` in Telegram admin DM, admin group, and public contexts.
+- [x] Add action-level policy enforcement before each Bot API call.
+- [x] Keep `telegram_send_file` as alias/wrapper over `telegram(action=send_file)`.
+- [x] Add TUI slash routes for delete-message(s) and tools policy.
+- [x] Add callback query polling and `answerCallbackQuery`.
+- [x] Add inline keyboard policy panel for admin toggles.
+- [x] Add tests for allowed deletes, denied deletes, rights failures, and callback
+      toggles.
+- [x] Update README once behavior is real.
+
+## Done Criteria
+
+This is complete when:
+
+1. An admin DM can ask the agent to delete a bot message or user message in a
+   known group, and the model calls `telegram(action="delete_message", ...)`.
+2. A public group user cannot cause deletion unless the sender is authenticated
+   admin, the action is enabled, the target is in the current chat, and the bot
+   has Telegram rights.
+3. The admin can open Telegram inline buttons to enable/disable action groups.
+4. The same policy can be changed from TUI slash commands.
+5. Tool results show enough provenance to audit what happened.