# Telegram Bridge

The Telegram bridge is a scoped public ingress and egress layer. It supports admin DMs, admin group mode, public group mode, media intake, generated artifact return, scoped memory, and persona documents.

## Start And Configure

```text
/telegram --key <bot-token>
/telegram --admin <telegram-user-id>
/telegram
/telegram status
/telegram stop
```

The TUI's right details sidebar includes a **TELEGRAM** dropdown after a bot is
configured. It shows bridge state, polling, interaction mode and work slots,
with controls for managing the bot and opening its settings. Click the heading
or focus it with Tab and press Enter or Space to expand it. On narrow terminals,
open **DETAILS** first. The dropdown remains available while the bot is stopped
or polling is disabled.

Workspace-owned bots use the daemon's existing controls. Settings that require
a worker restart are labeled as applying on the next start. A bot owned by
another terminal remains under that terminal's control.

## Workspace Services

The Omnius daemon supervises Telegram agents for registered workspaces, so a terminal does not need to stay open. A workspace must have its own saved `telegramKey`; global bot tokens are never copied across projects. Existing Telegram enablement, endpoint, credentials, and GPU selections still apply.

Open the daemon's **Projects** page, or the tray's **Telegram** menu, to inspect each agent and pause or resume it. **Start with daemon** controls automatic startup. Pausing checkpoints current work and saves the paused state before stopping the worker; the agent stays paused across daemon restarts and reboots until resumed. Turning off automatic startup leaves an already running agent active.

Each workspace runs in its own worker process. An agent already owned by a terminal session is shown as externally owned; Omnius preserves that owner. Updated terminal sessions also honor the workspace's saved pause state. A broken or unavailable workspace does not prevent the daemon and other workspaces from starting.

Administrators can use `GET /v1/projects/telegram` for status and `POST /v1/projects/telegram/control` with `root`, `action` (`start`, `pause`, `resume`, or `autostart`), and an `enabled` boolean for `autostart`. These routes use the daemon's normal API authentication. Bot tokens are not returned.

## BotFather Setup

1. Create the bot with BotFather and save the token through `/telegram --key <bot-token>`.
2. Disable privacy mode if the bot must read all group messages; leave privacy mode on if it should only see commands, mentions, and replies.
3. Add the bot to the target group and grant only the permissions it needs.
4. Send `/telegram --admin <telegram-user-id>` from the TUI before enabling public contexts.
5. Run `/telegram status` and verify bot username, admin user, mode, and connected chats.

## Access Matrix

| Context | Read Messages | Send Messages | Tools | Memory Scope |
| --- | --- | --- | --- | --- |
| Admin DM | yes | yes | admin policy | admin user |
| Admin group | replies, mentions, or all messages depending on BotFather privacy | only if Telegram grants send rights | configured group policy | group plus sender |
| Public group | scoped public intake | only if Telegram grants send rights | creative/public policy | group plus sender |
| No send rights | observed incoming messages only | no | no outbound retry loop | failure noted for that chat |

If Telegram returns a permanent write refusal, the bridge opens a durable read-only circuit for that chat. Later messages still enter scoped history, but they do not start reply inference. A time-gated `getChatMember` permission check must confirm restored text-write capability before reply inference resumes.

## Scope Model

Telegram context must preserve:

- chat ID
- user ID
- sender identity
- reply target
- media references
- group versus private scope

The agent must not collapse every participant into "the user." Persona and preference state is scoped by user and by group.

## Reply Preferences

Supported preference modes:

- quick full-context reply first, then notes after
- notes first, reply after
- simple rapid reply with tools and context but no extra notes stage

Preferences should be stored only when a user explicitly expresses a preference or an admin configures one. They should live in persona/state docs for that user or group scope.

| Mode | Behavior |
| --- | --- |
| `reply-first` | send the reply with full context first, then store notes/reflection after |
| `notes-first` | store notes/reflection first, then send the reply |
| `rapid` | reply with current tools and context, no extra notes stage |

Preference writes require an explicit tool decision. They are not selected by regex or chat heuristics.

## Failure Feedback

Telegram platform and tool failures remain raw trajectory evidence when the model can choose a corrected action. Permanent transport capability failures are different. The host must stop work that cannot be delivered.

The write-capability circuit classifies only caught `Error` objects and structured Bot API responses. It never scans participant text. `CHAT_WRITE_FORBIDDEN`, bot removal/blocking, missing send rights, and an unavailable chat open the chat-scoped circuit. A closed topic opens a topic-scoped circuit. These checks establish transport capability only; they do not classify conversational intent or decide whether a message deserves a reply.

Typing begins only after the relationship router returns a valid, input-bound `should_reply=true` decision. If the first typing action returns a permanent write refusal, Omnius does not retry without the topic, does not start a heartbeat, and does not generate the reply. Later read-only intake does not invoke the attention router.

Failure feedback should include:

- attempted method and destination chat ID
- Telegram API error object as returned
- message or media type attempted
- whether the failure happened before or after content generation
- current chat/user preference scope

Other feedback is ordinary trajectory evidence. It should not be converted into reward hacks or hidden conversational classifiers.

## Scheduled Reminders

Telegram reminders have two explicit outcomes:

- `person_notification` stores text and sends that text to the scoped person or chat when due.
- `agent_action` stores a task description, starts a new tool-capable run when due, and lets the host deliver the verified final result to the stored Telegram scope.

The legacy names `minimal` and `action` remain accepted for existing data. The
model must select the outcome from the requested future effect. “Remind me to
read the news at 09:00” is a person notification. “Get the news on topic X,
validate it, summarize it, and send it every morning at 9” is an agent action
with `repeat="daily"`, `time="09:00"`, and a complete `task_description`.

The scheduler claims each occurrence with a durable lease. It renews the lease
while the action runs. It increments `triggerCount` and advances recurrence only
after verified task completion and a target delivery receipt. A crash, incomplete
run, unavailable bridge, or failed send retains the occurrence and records
bounded exponential backoff. The host owns result delivery. An action task must
not send a second copy or create another reminder as a delivery workaround.

## Latency Adaptation

Telegram measures the full interval from intake receipt to a durable delivery receipt. Each chat/model pair starts with the full profile. A turn beyond the hard latency limit trials one leaner profile on the next real turn. Omnius does not issue duplicate inference to race profiles.

The normal router is a dependent decision cascade. Its first frame emits only route, reply authorization, actor role, reply basis, and cited evidence. A chat decision can proceed immediately. An action decision expands inside the task runner, where mission, effects, verification, and delivery are tracked. Durable peer-output classification is exposed only when the host packet contains repeated same-actor bot evidence. A strict retry uses the same small authorization frame and cannot create preferences, pattern memory, stimulation state, or expected-outcome side decisions.

This keeps ordinary human chat replies within a 320-token router ceiling. The 420-token recovery ceiling exists only for an invalid core contract. The larger contract is reserved for the evidence-gated repeated peer-output branch. More output capacity does not force generation, but the common path does not expose fields that the model does not need.

The full, balanced, and lean profiles preserve the typed relationship decision, action routing, evidence checks, and final Telegram receipt. Leaner chat profiles reduce optional context duplication and output ceilings. A failed typed contract or delivery receipt immediately returns the session to a richer profile. A leaner profile remains selected only after enough receipt-valid samples show no material quality-rate loss and at least a 10 percent median latency improvement.

Tuneables:

| Variable | Default | Purpose |
| --- | ---: | --- |
| `OMNIUS_TG_LATENCY_TARGET_MS` | `30000` | Desired end-to-end Telegram reply time |
| `OMNIUS_TG_LATENCY_HARD_MS` | `60000` | Latency that trials the next leaner profile |
| `OMNIUS_TG_LATENCY_MIN_SAMPLES` | `3` | Valid samples required before retaining a challenger |
| `OMNIUS_TG_LATENCY_SAMPLE_WINDOW` | `24` | Per-profile rolling comparison window |
| `OMNIUS_TG_WRITE_CAPABILITY_RECHECK_MS` | `300000` | Minimum interval between read-only permission probes |

## Public Creative Tools

Public users can create files, images, and audio through scoped creative workspaces under:

```text
.omnius/telegram-creative/<chat>/
```

These tools should not grant arbitrary filesystem access.

Every public artifact is retained as an encrypted per-chat object and bound to
a host-signed capability containing its logical path, byte length, content
hash, detected MIME type, source tool, expiry, delivery allowance, and review
receipts. The model cannot mint that capability. Telegram delivery verifies
the decrypted bytes against it and uses a durable, idempotent delivery job with
a lease, bounded backoff, and the returned Telegram message ID.

### Scoped create, edit, review, deliver loop

| Artifact | Typed tool | Supported work | Required review before delivery |
| --- | --- | --- | --- |
| Raster image | `safe_image_edit` | inspect, crop, resize, upscale/downscale, mask, composite, combine, convert | `telegram_image_analyze detail='full'` on the exact output |
| Audio | `audio_edit` | inspect, trim, concatenate, typed splice and silence, mix, normalize, fade, convert, resample | `audio_analyze` for sound/music or `transcribe_file` for speech |
| PDF or DOCX | `document` | create from heading/paragraph/bullet/page-break blocks, inspect, hash-guarded revise | `document action='inspect'` on the exact output |

Photo intake and `telegram_image_analyze` use the configured endpoint and model
with the original image. The backend must declare image support. If that
capability is unavailable, Omnius retains the image and reports it as unassessed.
These paths do not automatically select another vision model. An uncaptioned
photo retains its native media identity without inventing a caption or request.

These tools do not accept shell commands, raw FFmpeg filters, ImageMagick
expressions, raw PDF/OOXML bytes, HTML, macros, or paths outside the chat
workspace. Image and audio edits never overwrite an artifact. Document
revision requires `overwrite=true` and the `expected_hash` from the latest
receipt. A changed output receives a new content hash, so old review evidence
cannot authorize delivery of new bytes.

The image tool uses fixed ImageMagick argument vectors. The audio tool uses
fixed FFmpeg and FFprobe argument vectors. Both require those host programs to
be installed. The dependency-free document tool creates real PDF 1.4 and
OOXML DOCX files. PDF text uses the built-in WinAnsi font set; use DOCX for
full Unicode. DOCX pagination is explicitly reported as an estimate.

The agent must inspect the returned receipt, compare the reviewed evidence to
the user request, and create another output when the evidence exposes a gap.
Automatic attachment waits for the matching signed review receipt. Public
edits also use a separate per-user, per-chat hourly quota.

## Media Intake

Photos, documents, audio, video, and voice messages use a two-stage intake:

1. Pre-router ingress admits metadata, downloads through a hard byte cap, validates the container, and places the file in the bounded per-chat cache. It does not run ASR, vision, semantic audio inference, or durable memory ingestion.
2. After the attention router admits the turn, the agent selects the scoped evidence tool required by the request. Only grounded tool output can enter durable media memory.

Native filename, MIME type, byte size, duration, Telegram file identity, audio title, and performer are preserved. Cache filenames use the verified filename/MIME extension. Native MP3 and M4A audio are not relabeled as OGG. Concurrent eager and foreground consumers share one download by `file_unique_id`. Per-chat and process-wide item/byte limits use least-recently-used eviction. Explicit `reply` resolution follows a bounded reply chain and fails instead of silently selecting unrelated recent media.

Default ingress limits:

| Family | Bytes | Duration | Structural check |
| --- | ---: | ---: | --- |
| Raster image | 10 MiB | n/a | supported raster magic |
| Audio | 25 MiB | 10 minutes | audio-only `ffprobe`, 1-2 channels, 8-96 kHz |
| Video | 50 MiB | 10 minutes | video stream and probed duration |
| Other document | 25 MiB | n/a | scoped file boundary |

### Audio Evidence

Select tools from the requested outcome and the recording, not from a fixed keyword classifier:

| Needed evidence | Tool |
| --- | --- |
| Spoken words or lyrics | `transcribe_file` |
| Music, ambient sound, or general audio content | `audio_analyze` with `action='comprehend'` |
| Mixed speech and non-speech sound | both tools |

`transcribe_file` writes only into a run-scoped transcript directory in public/group mode, redacts absolute host paths, and does not create a second project-global transcript index. `audio_analyze` conditions ordinary MP3, OGG/Opus, M4A/AAC, and WAV input into a bounded mono PCM16/16 kHz analysis window.

Consumers must inspect typed quality, not only `success`:

- `data.quality.semantic.evidence_available=true` plus non-empty typed semantic evidence can validate semantic content.
- `data.status='speech'` plus a non-empty transcript can validate spoken content.
- `mode='acoustic_only'` proves only decoded, measured signal properties. It does not prove genre, instruments, performer, lyrics, or event identity.
- No-speech, embeddings, VAD, spectra, low-information classification, and unavailable semantic backends do not validate an acquired file against a content request.

Acquired public media remains blocked from delivery and `task_complete` until request-relevant evidence is recorded and Telegram returns a delivery message ID. Public automatic delivery consumes the same upload quota as explicit `telegram_send_file` calls. User policy blocks apply to dynamically constructed creative, audio, acquisition, and send tools.

## Verification

Relevant focused tests include `telegram-media-admission.test.ts`, `telegram-media-cache.test.ts`, `telegram-media-evidence.test.ts`, `telegram-public-media.test.ts`, `telegram-artifact-ledger.test.ts`, `telegram-creative-tools.test.ts`, `safe-image-edit.test.ts`, `audio-edit.test.ts`, `document.test.ts`, Telegram delivery preferences, inference error suppression, reflection corpus, and Bot API compatibility tests.
