Move the bundled Telegram channel out of tree into an archipelago channel extension #1399

Closed
opened 2026-10-27 13:40:14 +00:00 by sam · 0 comments
Owner

Telegram is still a bundled channel in archiemessaging: internal/channels/telegram
is 17 files, 4788 lines, no tests, and is under active development, while
internal/channels holds the generic seam plus that one concrete channel.
archiemessaging builds it by hand and type-asserts to *telegram.Gateway in four
places. archipelago ships only an email channel package.

The extension machinery the bead assumed is in place and is not the work:
proto/channel/v1 (lifecycle stream, settings, secrets, chat_broker_id),
internal/infrastructure/channelext (the broker bridge that implements
channels.Channel over a brokered ChatService), extension_channels.go (installs,
resolves _ref secrets, runs channel packages), the generic extension-settings
store, and archipelago/sdk generated from core's proto. gateway.v1 ChatService
already carries everything ordinary traffic needs: Ask/Answer covers clarify,
picker, approval and questionnaire, and Stream/ToolCall/Media covers streaming
tool calls, attachments and ephemeral replies. No new messaging contract is
needed.

What blocks the move is five host-only seams that telegram_features.go wires by
hand — Updates (releaseupdate Check/Defer/Install plus a workdir report file),
ReleaseAnnouncements (releaseannounce.Announcer with hashed workdir state),
RunningVersions (presence store), SetShowToolCalls (chat.show_tool_calls), and
Reload (ReloadChannel exists, but extension channels declare
ReloadSupported:false and their rebuild is a no-op closure). Each needs a
contract home on ChatService or channel.v1, or should be deleted. That decision
is the maintainer's and comes before any porting.

Second structural gap: extension channels are composed once at startup and never
reconciled, so moving Telegram out inherits archie-core-teaq (enabling or
disabling a channel needs a restart) as a regression. Today Telegram enables,
disables and restarts live.

Done when: Telegram runs as an archipelago channel package; internal/channels/
telegram, telegram_features.go, and every *telegram.Gateway assertion and
telegram-specific case in core are deleted; internal/channels holds only the
generic seam; the five seams above have a home or are gone; extension channels
reconcile their settings without a service restart; and the open Telegram beads
are re-pointed or closed.

Full coupling inventory, seam detail and sequencing are in the design notes.

Estimate: not a port of 4788 lines. The email reference package is 262 lines
including packaging. The cost is the five seams and the reconcile gap.

Design

VERIFIED STATE (at investigation)
Not started. internal/channels/telegram: 17 files, 4788 lines, 0 _test.go.
Archipelago: channels/email only, no telegram package. Last telegram commits
are features, not removal (79b5e8fc /approve, c56344ea /stop, b468fb8b clarify
and picker fallback, 52bbb74b voice transcription, 96267811 ephemeral TTL).
Every commit to the package grows the thing to be moved.

WHAT IS ALREADY BUILT (do not rebuild)

  • proto/channel/v1/channel.proto: ChannelService.Run stream; RunRequest carries
    settings, secrets (host resolves _ref as engine:key), and chat_broker_id, the
    plugin broker stream the host serves gateway.v1.ChatService on.
  • internal/infrastructure/channelext: bridge implementing channels.Channel over
    the brokered ChatService.
  • internal/app/archiemessaging/extension_channels.go: openExtensionChannels
    discovers installed channel packages, resolves _ref settings through the
    secret registry, materializes the binary by digest, and returns
    channelInstances whose rebuild is a no-op closure.
  • Generic extension-settings store (extension_settings); email already gets its
    credentials this way.
  • archipelago/sdk/gateway/v1 is generated from core's proto per archipelago
    README, so an out-of-tree channel uses pb types, not core internals.
  • gateway.v1 covers ordinary traffic completely. Ask{approval, picker, clarify,
    questionnaire} + AnswerRequest(ask_id, answer); StreamResponse{kind, text,
    session_id, tool, media, ask}. Nothing about clarify/picker/approval/streaming
    needs new contract work.

CORE WIRING TO DELETE (file:line)

  • app/archiemessaging/compose.go:15,166-170,190-210 composeTelegram and
    telegramValidateConfigMap; the token-empty warning at 190-191.
  • app/archiemessaging/reconcile.go:11,82 and applyChannelEnablement (124-136),
    applyShowToolCalls (140-147), channelChanges (150-161): telegram token and
    allowlist enablement, transport-change restart, in-place show-tool-calls.
  • app/archiemessaging/channel_status.go:10,45-56: channelReloadable and
    ReloadChannel both type-assert *telegram.Gateway; ReloadSupported is derived
    from that assertion, so an extension channel always declares false.
  • app/archiemessaging/telegram_features.go: whole file (~110 lines),
    configureTelegram + gatewayVersionReporter + telegramReloader +
    identityStatePath.
  • config/config.go:914-975 TelegramConfig, ChatConfig.Telegram; chat_frontends.go
    FrontEnds() returns a hardcoded telegram entry and AnyFrontEndConfigured feeds
    the setup checklist (webui/api_setup.go:46-49 "Chat channel", generic path to
    /settings/channels).
  • app/controlplane/channel_settings.go:14,27 telegramSettings inside the stored
    ChannelSettings document; controlplanerpc.TelegramSettings.
  • webui/api_config.go:81 channelViewFromStatus hardcoded telegram (and email)
    descriptions; api_config.go:150,232 ChatView.ShowToolCalls and
    ChannelConfigured; api_chat.go:574 meta.Channel = "telegram".
  • ui/src/channels/ChannelsPage.vue:45,89,91,95,99-102,147-150 hardcoded telegram
    panel and description map.

THE FIVE HOST-ONLY SEAMS (the real cost; each needs a home or deletion)

  1. Updates: g.Updates = releaseupdate.Service (Check/Defer/Install against the
    stored update settings) plus g.UpdateReportPath, a hashed workdir state file
    (releaseupdate.ReadPendingReport/ClearPendingReport). No RPC serves updates on
    any proto. Behind it: internal/releaseupdate (~2200 lines incl. verify) and
    internal/releaseannounce (277). Owner decision: contract home on ChatService
    or delete /update from chat.
  2. ReleaseAnnouncements: releaseannounce.Announcer with StatePath under the
    daemon workdir, compared against buildinfo.Version and configtemplate.
    Changelog. Pure host filesystem state; a different path would replay every
    announcement already shown. Owner decision: host-owned loop that pushes
    announcements to channels, or delete and keep announcements dashboard-only.
  3. RunningVersions: servicekit.RunningVersions over the presence store. No RPC.
    Needed by the update report to verify what is actually running.
  4. SetShowToolCalls: cfg.ShowToolCalls from chat.show_tool_calls. There is no RPC
    for it and it is read per reply, so it is currently applied in place on the
    running gateway without a restart.
  5. Reload: ChatService.ReloadChannel exists and works, but an extension channel
    cannot reload — rebuild returns the same instance. Reload for an extension
    means re-launching the plugin with new settings from the extension-settings
    store. Closing this also closes archie-core-np7l and archie-core-oif3.

STRUCTURAL GAP: EXTENSION CHANNELS DO NOT RECONCILE
run.go:86 calls openExtensionChannels once at startup; reconcileOnce only ever
looks at ResolvedConfig.Telegram and ShowToolCalls. Nothing re-reads
extension_settings, rebuilds a plugin, or honours an enablement change. Moving
Telegram out before this is fixed is a regression against today's live
enable/disable/restart (archie-core-teaq). Requires extension settings to offer
an observable version, as ChannelSettings does, and channelInstance.rebuild to
actually relaunch.

PRESENTATION LOGIC IS IN THE DOMAIN PACKAGE
internal/domain/messaging is 2268 lines. RenderToolCall (tool_render.go, 313
lines), InteractiveOf and TextFallback are used only by the telegram package, so
they must move out with it, be published, or be duplicated. internal/gateway
aliases the rest (MsgText, NewTurns, CapabilitiesOf, InteractiveOf, TextFallback)
so wire-shaped types port to sdk/gateway/v1 cleanly. Decide per symbol; do not
bulk-move the package.

PACKAGE COUPLING TODAY
internal/channels/telegram imports exactly three core packages: internal/channels
(the seam), internal/domain/messaging (30-odd wire/behaviour types), and
internal/releaseupdate. Everything else is the Telegram bot library. That short
import list is why the port is mostly mechanical once the seams are decided.

EMAIL AS REFERENCE
archipelago channels/email: main.go 262 lines, main_test.go, package.yaml with
contributes.extensions[surface: channel, path: bin/email]. Pack with
scripts/pack.sh, publish with scripts/publish.sh. Copy that shape.

SEQUENCING

  1. Decide the fate of Updates, ReleaseAnnouncements, RunningVersions,
    ShowToolCalls (maintainer decision, needs a home on ChatService or deletion).
  2. Make extension channels reconcile: settings version + rebuild, so
    enable/disable/reload work for any channel package. Closes teaq and np7l.
  3. Add Reload to the extension contract (either channel.v1 or host-side
    relaunch) and stop deriving ReloadSupported from a concrete type — replace
    the assertion in channel_status.go with a channels.Reloader interface.
  4. Port the package: port.go, then delete the core files listed above and the
    config/controlplane/webui/UI telegram cases in one commit so no half-state.
  5. Re-point or close the Telegram beads listed below.

RELATED OPEN BEADS
archie-core-teaq enabling or disabling a channel needs a service restart
archie-core-np7l channel reload request surface
archie-core-oif3 webui(config): add Reload Telegram once a restart RPC exists
archie-core-8ngsp update announcement omits skipped releases, raw markdown in
Telegram (dies with seam 1 if /update is deleted)
archie-core-olycr telegram: /model Route calls carry no sender or platform
archie-core-fhsd verify /branch over Telegram end to end
archie-core-oif3 and np7l are step 3; 8ngsp is step 1; olycr and fhsd should be
fixed in the package after the port, not before.
Also on the same seam and unaffected by ordering: archie-core-mqti.5 (email),
archie-core-mqti.6 (Discord or Slack).

UNESTIMATED
The 4788 lines were not read line by line. The inventory above comes from
imports, type assertions and call sites. Per-file porting difficulty inside the
package (richblocks, live.go rendering, polling_readiness) is unmeasured.

CONSTRAINTS
Repo-relative paths only in this document by design. task check gates the
commit. Generated files (ui/dist, protobuf) regenerate with the change that
caused them. No new compatibility shims: the bundled path is deleted, not
deprecated.

Acceptance criteria

Telegram runs as an archipelago channel package. internal/channels/telegram and telegram_features.go are deleted, internal/channels holds only the generic seam, and no *telegram.Gateway assertion or telegram-specific case remains in core config, controlplane, webui or UI. The five host-only seams (Updates, ReleaseAnnouncements, RunningVersions, SetShowToolCalls, Reload) each have a contract home or are deleted. Extension channels reconcile their settings and support reload without a service restart. The open Telegram beads are re-pointed or closed.


Imported from beads archie-core-jl7ti · GitHub #1532 · type feature · priority P2 · created 2026-10-10

Telegram is still a bundled channel in archiemessaging: internal/channels/telegram is 17 files, 4788 lines, no tests, and is under active development, while internal/channels holds the generic seam plus that one concrete channel. archiemessaging builds it by hand and type-asserts to *telegram.Gateway in four places. archipelago ships only an email channel package. The extension machinery the bead assumed is in place and is not the work: proto/channel/v1 (lifecycle stream, settings, secrets, chat_broker_id), internal/infrastructure/channelext (the broker bridge that implements channels.Channel over a brokered ChatService), extension_channels.go (installs, resolves _ref secrets, runs channel packages), the generic extension-settings store, and archipelago/sdk generated from core's proto. gateway.v1 ChatService already carries everything ordinary traffic needs: Ask/Answer covers clarify, picker, approval and questionnaire, and Stream/ToolCall/Media covers streaming tool calls, attachments and ephemeral replies. No new messaging contract is needed. What blocks the move is five host-only seams that telegram_features.go wires by hand — Updates (releaseupdate Check/Defer/Install plus a workdir report file), ReleaseAnnouncements (releaseannounce.Announcer with hashed workdir state), RunningVersions (presence store), SetShowToolCalls (chat.show_tool_calls), and Reload (ReloadChannel exists, but extension channels declare ReloadSupported:false and their rebuild is a no-op closure). Each needs a contract home on ChatService or channel.v1, or should be deleted. That decision is the maintainer's and comes before any porting. Second structural gap: extension channels are composed once at startup and never reconciled, so moving Telegram out inherits archie-core-teaq (enabling or disabling a channel needs a restart) as a regression. Today Telegram enables, disables and restarts live. Done when: Telegram runs as an archipelago channel package; internal/channels/ telegram, telegram_features.go, and every *telegram.Gateway assertion and telegram-specific case in core are deleted; internal/channels holds only the generic seam; the five seams above have a home or are gone; extension channels reconcile their settings without a service restart; and the open Telegram beads are re-pointed or closed. Full coupling inventory, seam detail and sequencing are in the design notes. Estimate: not a port of 4788 lines. The email reference package is 262 lines including packaging. The cost is the five seams and the reconcile gap. ### Design VERIFIED STATE (at investigation) Not started. internal/channels/telegram: 17 files, 4788 lines, 0 _test.go. Archipelago: channels/email only, no telegram package. Last telegram commits are features, not removal (79b5e8fc /approve, c56344ea /stop, b468fb8b clarify and picker fallback, 52bbb74b voice transcription, 96267811 ephemeral TTL). Every commit to the package grows the thing to be moved. WHAT IS ALREADY BUILT (do not rebuild) - proto/channel/v1/channel.proto: ChannelService.Run stream; RunRequest carries settings, secrets (host resolves _ref as engine:key), and chat_broker_id, the plugin broker stream the host serves gateway.v1.ChatService on. - internal/infrastructure/channelext: bridge implementing channels.Channel over the brokered ChatService. - internal/app/archiemessaging/extension_channels.go: openExtensionChannels discovers installed channel packages, resolves _ref settings through the secret registry, materializes the binary by digest, and returns channelInstances whose rebuild is a no-op closure. - Generic extension-settings store (extension_settings); email already gets its credentials this way. - archipelago/sdk/gateway/v1 is generated from core's proto per archipelago README, so an out-of-tree channel uses pb types, not core internals. - gateway.v1 covers ordinary traffic completely. Ask{approval, picker, clarify, questionnaire} + AnswerRequest(ask_id, answer); StreamResponse{kind, text, session_id, tool, media, ask}. Nothing about clarify/picker/approval/streaming needs new contract work. CORE WIRING TO DELETE (file:line) - app/archiemessaging/compose.go:15,166-170,190-210 composeTelegram and telegramValidateConfigMap; the token-empty warning at 190-191. - app/archiemessaging/reconcile.go:11,82 and applyChannelEnablement (124-136), applyShowToolCalls (140-147), channelChanges (150-161): telegram token and allowlist enablement, transport-change restart, in-place show-tool-calls. - app/archiemessaging/channel_status.go:10,45-56: channelReloadable and ReloadChannel both type-assert *telegram.Gateway; ReloadSupported is derived from that assertion, so an extension channel always declares false. - app/archiemessaging/telegram_features.go: whole file (~110 lines), configureTelegram + gatewayVersionReporter + telegramReloader + identityStatePath. - config/config.go:914-975 TelegramConfig, ChatConfig.Telegram; chat_frontends.go FrontEnds() returns a hardcoded telegram entry and AnyFrontEndConfigured feeds the setup checklist (webui/api_setup.go:46-49 "Chat channel", generic path to /settings/channels). - app/controlplane/channel_settings.go:14,27 telegramSettings inside the stored ChannelSettings document; controlplanerpc.TelegramSettings. - webui/api_config.go:81 channelViewFromStatus hardcoded telegram (and email) descriptions; api_config.go:150,232 ChatView.ShowToolCalls and ChannelConfigured; api_chat.go:574 meta.Channel = "telegram". - ui/src/channels/ChannelsPage.vue:45,89,91,95,99-102,147-150 hardcoded telegram panel and description map. THE FIVE HOST-ONLY SEAMS (the real cost; each needs a home or deletion) 1. Updates: g.Updates = releaseupdate.Service (Check/Defer/Install against the stored update settings) plus g.UpdateReportPath, a hashed workdir state file (releaseupdate.ReadPendingReport/ClearPendingReport). No RPC serves updates on any proto. Behind it: internal/releaseupdate (~2200 lines incl. verify) and internal/releaseannounce (277). Owner decision: contract home on ChatService or delete /update from chat. 2. ReleaseAnnouncements: releaseannounce.Announcer with StatePath under the daemon workdir, compared against buildinfo.Version and configtemplate. Changelog. Pure host filesystem state; a different path would replay every announcement already shown. Owner decision: host-owned loop that pushes announcements to channels, or delete and keep announcements dashboard-only. 3. RunningVersions: servicekit.RunningVersions over the presence store. No RPC. Needed by the update report to verify what is actually running. 4. SetShowToolCalls: cfg.ShowToolCalls from chat.show_tool_calls. There is no RPC for it and it is read per reply, so it is currently applied in place on the running gateway without a restart. 5. Reload: ChatService.ReloadChannel exists and works, but an extension channel cannot reload — rebuild returns the same instance. Reload for an extension means re-launching the plugin with new settings from the extension-settings store. Closing this also closes archie-core-np7l and archie-core-oif3. STRUCTURAL GAP: EXTENSION CHANNELS DO NOT RECONCILE run.go:86 calls openExtensionChannels once at startup; reconcileOnce only ever looks at ResolvedConfig.Telegram and ShowToolCalls. Nothing re-reads extension_settings, rebuilds a plugin, or honours an enablement change. Moving Telegram out before this is fixed is a regression against today's live enable/disable/restart (archie-core-teaq). Requires extension settings to offer an observable version, as ChannelSettings does, and channelInstance.rebuild to actually relaunch. PRESENTATION LOGIC IS IN THE DOMAIN PACKAGE internal/domain/messaging is 2268 lines. RenderToolCall (tool_render.go, 313 lines), InteractiveOf and TextFallback are used only by the telegram package, so they must move out with it, be published, or be duplicated. internal/gateway aliases the rest (MsgText, NewTurns, CapabilitiesOf, InteractiveOf, TextFallback) so wire-shaped types port to sdk/gateway/v1 cleanly. Decide per symbol; do not bulk-move the package. PACKAGE COUPLING TODAY internal/channels/telegram imports exactly three core packages: internal/channels (the seam), internal/domain/messaging (30-odd wire/behaviour types), and internal/releaseupdate. Everything else is the Telegram bot library. That short import list is why the port is mostly mechanical once the seams are decided. EMAIL AS REFERENCE archipelago channels/email: main.go 262 lines, main_test.go, package.yaml with contributes.extensions[surface: channel, path: bin/email]. Pack with scripts/pack.sh, publish with scripts/publish.sh. Copy that shape. SEQUENCING 1. Decide the fate of Updates, ReleaseAnnouncements, RunningVersions, ShowToolCalls (maintainer decision, needs a home on ChatService or deletion). 2. Make extension channels reconcile: settings version + rebuild, so enable/disable/reload work for any channel package. Closes teaq and np7l. 3. Add Reload to the extension contract (either channel.v1 or host-side relaunch) and stop deriving ReloadSupported from a concrete type — replace the assertion in channel_status.go with a channels.Reloader interface. 4. Port the package: port.go, then delete the core files listed above and the config/controlplane/webui/UI telegram cases in one commit so no half-state. 5. Re-point or close the Telegram beads listed below. RELATED OPEN BEADS archie-core-teaq enabling or disabling a channel needs a service restart archie-core-np7l channel reload request surface archie-core-oif3 webui(config): add Reload Telegram once a restart RPC exists archie-core-8ngsp update announcement omits skipped releases, raw markdown in Telegram (dies with seam 1 if /update is deleted) archie-core-olycr telegram: /model Route calls carry no sender or platform archie-core-fhsd verify /branch over Telegram end to end archie-core-oif3 and np7l are step 3; 8ngsp is step 1; olycr and fhsd should be fixed in the package after the port, not before. Also on the same seam and unaffected by ordering: archie-core-mqti.5 (email), archie-core-mqti.6 (Discord or Slack). UNESTIMATED The 4788 lines were not read line by line. The inventory above comes from imports, type assertions and call sites. Per-file porting difficulty inside the package (richblocks, live.go rendering, polling_readiness) is unmeasured. CONSTRAINTS Repo-relative paths only in this document by design. task check gates the commit. Generated files (ui/dist, protobuf) regenerate with the change that caused them. No new compatibility shims: the bundled path is deleted, not deprecated. ### Acceptance criteria Telegram runs as an archipelago channel package. internal/channels/telegram and telegram_features.go are deleted, internal/channels holds only the generic seam, and no *telegram.Gateway assertion or telegram-specific case remains in core config, controlplane, webui or UI. The five host-only seams (Updates, ReleaseAnnouncements, RunningVersions, SetShowToolCalls, Reload) each have a contract home or are deleted. Extension channels reconcile their settings and support reload without a service restart. The open Telegram beads are re-pointed or closed. --- _Imported from beads `archie-core-jl7ti` · GitHub #1532 · type feature · priority P2 · created 2026-10-10_
sam added the mediumfeature labels 2026-10-27 13:40:14 +00:00
sam self-assigned this 2026-10-27 13:40:14 +00:00
sam closed this issue 2026-11-08 12:40:06 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sam/archie#1399