oh-my-pi-telegram/docs/superpowers/specs/2026-07-15-telegram-omp-status-design.md

Telegram OMP 17 status indicator

Goal

Make the Telegram bridge visible in OMP 17's upper status bar, immediately after the cost segment, and correct the OMP installation guidance. Configure a replacement bot token only through the local interactive OMP setup flow.

Scope

• Add a public OMP extension API for a status-bar segment placed after cost.
• Have @evandrodevbr/oh-my-pi-telegram register one segment through that API.
• Update the segment when bridge polling starts, stops, fails, or a session is replaced.
• Update the plugin README with OMP 17 plugin commands and secure setup instructions.

OMP core API

OMP owns status-bar ordering and rendering. The API accepts a keyed text segment and exposes only the supported placement:

• after: "cost"
• a stable extension key
• plain text supplied by the extension

OMP sanitizes extension text using the existing status-text sanitizer and renders registered segments after its own cost segment, before subsequent built-in segments. An extension clears its segment by passing undefined. Extension segments cannot choose arbitrary insertion positions or access the status-line component directly.

The implementation belongs in a versioned OMP source checkout or fork, not the global Bun installation, because omp update replaces global package files.

Telegram bridge behavior

The plugin registers the telegram segment once the extension UI is available. It derives the value from the existing bridge status runtime:

Runtime condition	Status-bar text
Telegram polling active	Telegram: conectado
Telegram polling inactive	Telegram: desconectado

The plugin updates the registered segment through its existing status update flow. This covers /telegram-connect, /telegram-disconnect, polling errors and recovery, lock ownership changes, and session lifecycle updates. It does not make a network request merely to render a status value.

Configuration

The replacement token is configured only in an interactive local OMP session:

/telegram-setup
/telegram-connect

The token must not be put in chat, source code, README examples, committed configuration, test fixtures, logs, or terminal output. The plugin continues using its existing local configuration file and profile behavior.

README

The primary OMP installation commands become:

omp plugin install npm:@evandrodevbr/oh-my-pi-telegram
omp plugin install git:github.com/evandrodevbr/oh-my-pi-telegram
omp plugin link /path/to/oh-my-pi-telegram

The README states that an OMP session must be restarted after installation or linking, then documents /telegram-setup, /telegram-connect, /telegram-disconnect, and /telegram-status.

Verification

• OMP unit test: a registered extension segment is rendered immediately after cost; clearing it removes it; text is sanitized.
• Telegram plugin test: active polling renders Telegram: conectado; inactive polling renders Telegram: desconectado; the current UI registration API is exercised.
• Plugin type-check and public-package tests pass.
• OMP 17 smoke test: the linked plugin loads and /telegram-status returns.
• Manual local configuration: /telegram-setup validates the new bot token, /telegram-connect activates polling, and the status bar changes state.

Non-goals

• No direct modification of global Bun-installed OMP files.
• No status segment placement other than after cost.
• No retry policy, network health probe, or separate Telegram connection abstraction.
• No token migration or token disclosure.