telegram

Files (20)

• SKILL.md
• miniapp_registration.py · lib/
• telegram_api.py · lib/
• telegram_health.py · lib/
• telegram_i18n.py · lib/
• telegram_inbound.py · lib/
• telegram_notifier.py · lib/
• telegram_quiz.py · lib/
• telegram_state.py · lib/
• telegram_typing.py · lib/
• plugin.py
• cloudflare_tunnel.py · scripts/
• companion.py · scripts/
• platform_support.py · scripts/
• public_gateway.py · scripts/
• runtime_status.py · scripts/
• sidecar.py · scripts/
• telegram_menu.py · scripts/
• telegram_settings.py · scripts/
• tunnel_watchdog.py · scripts/

SKILL.md (first lines)

# Telegram

One owner-only Telegram integration provides both the established bot bridge
and the optional Mini App. The first positive private Telegram chat binds as
the sole owner. Text, photos and files (documents, video, audio and voice notes within
this integration's 10 MiB download cap) can be sent to Ouroboros, with or without a
caption; replies, photos, videos, documents, typing state, subagent cards, quiz
cards, and opt-in notifications are mirrored back to that owner. Telegram's typing
indicator stays on while a reply you asked for, mirrored to this chat, is actively
being prepared by Ouroboros or a working helper; it stops for Pause, Stop now and
after the answer, and a question waiting for you, a model-access wait or background work
never keep it on (DESIGN §9). A quiz card is
answered by tapping an option or by replying to the card with a free-form
answer; both reach the same host decision ingress as the web UI. The bridge speaks
the install's interface language (Settings → Appearance → Language, or `/language`
here): its own lines are English source translated by the install's translation
memory, so the bot ships no dictionary and follows any language the owner chooses. Owner `/panic`
is available in every command mode, including strict: it sends once through the emergency door,
never queues or replays. Telegram dates before the host's whole-second import time are refused;
their previous outcome is unknown. This assumes aligned clocks: a host ahead rejects fresh Panic
until Telegram reaches that second; a host behind can accept retained commands. Dates in the
boundary second are accepted. Other slash commands keep their command-mode rules even in replies; quote a literal command
as code or include it inside an explanation to send it as a quiz answer.

Version 1.3 remembers every mirrored part, including media and completion
notices, in a bounded durable message map. Replying passes its host row or work
reference through normal chat; Ouroboros decides what it means. Unknown or
evicted ids add nothing. Answers to an earlier owner message from this Telegram
chat use a native reply; answers to its latest owner message stay unquoted.
Silent mode edits only within one task episode and reply origin; Continue
episodes remain separate messages. Relay success stays silent; a host-reported
failure arrives as one line. A relayed row quotes the owner's words verbatim as
plain text, under where he wrote them and with the file names, above the note; a
note between works that quotes none of his words stays in its room.
Quiz buttons and replies keep their decision path; earlier parts of a long
question carry ordinary references.

Version 1.3.2 warns when the derived reference map cannot be saved, without
blocking an owner message or later outbound parts. Completion notifications
reference their work, not an authored answer shown only in Main.
Version 1.3.3 gives a finished root task's notice the task card's cost words for
its whole tree: `$3.42` when final, `up to $3.42` while costs may still arrive,
`Tracked:` when some step has no price; an unknown cost adds nothing.
Version 1.3.6 sends Wrap up's saved-work receipt, which the host types as a terminal
receipt, even with progress mirroring off; other card rows still follow that toggle.
Version 1.3.7 sends no finish notification for a run that finished quietly.

Version 1.2.1 marks questions that wait for an owner answer and clears the
waiting line after an answer submitted through Telegram.
Version 1.2.3 serves the stored settings on GET settings/save so the Settings
form shows saved values before Save, and shortens the four long option labels.
Version 1.2.4 introduced a non-clean completion notice even with the task toggle off;
version 1.2.14 replaces that policy with a true opt-out (below).
Version 1.2.5 shows the whole quiz card: its project, the host's facts about the
asking task, and every option's detail, with localized field names; a card too
long for one Telegram message arrives as ordered parts followed by the keyboard
message, and nothing authored is cut.
Version 1.2.6 edits a sent question card on its lifecycle (`chat.quiz_state`): a
web answer settles it, a closed wait drops the waiting line yet keeps buttons,
a finished task says a late answer still counts, and (1.2.13) a question closed
unanswered states that and its reason without buttons. Answers and closures are final.
An open question (no options) is the same whole card without buttons; it asks for
a reply in your own words.

Version 1.2.9 routes every Telegram API call through the optional skill-local
`TELEGRAM_PROXY` setting, including polling, sends, downloads, notifications,
and the companion's menu button lifecycle. The Settings form masks the proxy
and never reads its stored credentials back into the browser.

Version 1.2.10 also forwards the owner's notes and skill notices (`reminder` and
`skill_notice` System rows, written for the owner) to the pinned chat when the
mirror mode is `telegram_only`; mode `all` already mirrored them.

Version 1.2.11 speaks the install's interface language: `/language` lists English
and the languages the install already has, `/language <name or tag>` chooses one
for the whole installation through the host's one writer, and the bridge's own
menu, buttons, card hints and notifications are read through the install's
translation memory (a line it lacks is generated like a browser miss). The
retired bridge-only `TELEGRAM_LANGUAGE` setting is migrated once.

Version 1.2.12 starts the Mini App when the Ouroboros server is a container's
PID 1 without an init. PID 1 counts as the server only when the host named
itself so; a companion adopted by init or a subreaper still stops.

Version 1.2.14 makes `TELEGRAM_NOTIFY_TASKS=off` suppress every additional task
completion notice, failures and cancellations included. On sends completion
notices with the host's material causes; pure review provenance and missing
host-verification receipts stay in task details, without declaring success.
Required, unresolved or unknown review obligations remain disclosed. Previously
stored Off values now mean no extra notices; no setting is migrated or added.
The status-only Main mirror follows this toggle too; preserved intermediate
content still arrives. Ordinary replies, files and questions are independent, as is
`TELEGRAM_SILENT_MODE` (editing consecutive replies). IDs observed while Off
remain seen, so enabling does not replay that backlog. Older summary rows without
the host's compact cause projection retain their original reason text when On.

The Mini App exposes the unchanged Ouroboros SPA through the established
owner-authenticated sidecar and a pinned Cloudflare Quick Tunnel. It is enabled
by default after owner binding and can be turned off independently without
stopping the text bridge. Disabling the skill destroys process-memory Mini App
sessions, stops public exposure, and best-effort restores the prior Telegram
menu button. Rotate the bot token only while the skill is disabled, then
re-enable it.

Delegated task cards lead with the executor's latest words (marked earlier
when retained), followed by problems and compact activity counts. These are
attributed observations, not the supervising task's narration or a completion
receipt; journal gaps and preview omissions remain visible.

Set `TELEGRAM_BOT_TOKEN` in Settings, grant it to this skill, enable the skill,
and send the bot a private message to bind the owner. No legacy Telegram skill
state is copied or changed. Installations that use `telegram-bridge` or
`telegram-miniapp-poc` must disable or remove those skills before enabling this
one.

If Telegram requires a proxy, open this skill's Telegram settings and enter
`TELEGRAM_PROXY` as `scheme://[user:password@]host[:port]` (`socks5`, `socks5h`,
`http` or `https`; SOCKS needs an explicit port). Leave the masked field empty
to keep a saved value, or use **Clear saved Telegram proxy** to remove it.

From razzant/ouroboros, MIT.

More from razzant/ouroboros