# kcode-kennedy-telegram-runtime
`kcode-kennedy-telegram-runtime` owns the application-level workflow between
durable Telegram transport work and Kennedy logical sessions. It is deliberately
separate from the raw bot transport, the Telegram session coordinator, and the
general Kennedy orchestration library.
The runtime normalizes queued text and media, resolves Telegram identities and
their Kweb roots, creates or restores private and group sessions, executes turns
through the shared orchestration control, delivers exact text/object responses,
handles reset and interruption, rolls idle sessions over after six hours,
repairs detached group state, prepares group ingress, and schedules wakeups.
It does not own Telegram network polling or queue persistence; those remain in
`kcode-tg-kennedy-bot`. It does not implement session tool loops or checkpoint
conflict rules; those remain in `kcode-kennedy-orchestration` and
`kcode-kennedy-sessions`.
## Public API
### `Config`
`telegram_max_media_bytes` is the maximum object size offered to Telegram
sessions and enforced before response delivery. `telegram_web_user_handle` is
the configured identity handle used to distinguish the web user in group
context.
### `Runtime`
`Runtime::new` accepts `Config`, the shared orchestration `Orchestrator`, and a
`kcode-kennedy-roots::DirectoryRoots` capability. All runtimes constructed from
the same orchestration control share conversation locks, active-operation
cancellation state, checkpoint behavior, prompt composition, and the global
Kweb writer mutex.
`Runtime::run` validates dependencies, repairs pending durable state, starts the
four-hour UTC wakeup scheduler, and polls Telegram events, group-session context
updates, group-ingress batches, and expired private sessions until failure or
cancellation.
## Retry and completion behavior
Transport events remain pending until their response, reset, abort, or
interruption is durably recorded by the Telegram transport. Transient failures
use bounded exponential backoff. A turn is capped at 90 minutes, after which the
session is checkpointed for ingress and the transport receives a timeout notice.
An identical Session History state-conflict checkpoint is treated as successful
by the shared orchestration control.
Group media metadata is checked before downloading bytes. Group-context files
retain transport identifiers and provenance metadata. Native Telegram media
kinds and filename overrides are preserved for response delivery, and Kennedy's
text is used as an exact caption only when Telegram permits it.