Channel reload request surface: the UI asks the Messaging Service to reload a channel #1474
Notifications
Due Date
No due date set.
Depends on
Reference: sam/archie#1474
Reference in new issue
Block a user
Split out of archie-core-8cda.6.8 when its read path landed (
96aa05c4). Reporting channel lifecycle to the dashboard is done; this is the opposite direction and has a different lifetime, so it is its own object rather than a field on the status resource.WHY A SEPARATE SURFACE (decided, with the reasoning)
A status surface is writer-is-service, reader-is-UI. A reload request inverts that, so putting it on the status resource would (a) make READING status capable of re-triggering an action, (b) make a transient request indistinguishable from state once anything polls, and (c) force the service to clear a field of an object whose contract is that the service reports it. A request queue and a status report do not share a lifetime, and a surface with a different lifetime should be a different surface.
WHAT EXISTS NOW
WHAT THIS BEAD OWNS
A request surface the service observes and clears, with its own lifetime, plus the UI action that writes it and the service side that consumes it. The contract PRD's grouped table gains its group in the same change that adds the RPCs.
ACCEPTANCE: against a running service, reload works for a channel declaring ReloadSupported and is refused clearly for one that does not; and the status surface's contract is unchanged in shape (writer stays the service).
DEPENDS ON: nothing - unblocked.
Imported from beads
archie-core-np7l· GitHub #1106 · type feature · priority P2 · created 2026-09-21sam wrote (originally 2026-10-05):
Folded in from archie-core-mqti.1 (split 2026-10-05). mqti.1 delivered the Skills and Curators surfaces (gateway ListSkills/CuratorHealth RPCs plus the archie-ui clients wired in compose.go, commit
6bde185e) and briefly wired Server.ReloadChannel to a gateway ReloadChannel client. A Gateway hosts no channels, so that call only ever answered Unavailable and /api/channels/{id}/reload returned 502; it is now unwired (commit9bb20830) and reload answers 501 again, matching WHAT EXISTS NOW above. The gateway ReloadChannel RPC is still in proto/gateway/v1/chat.proto: proto:lint (buf breaking against branch=main) refuses to delete it until main carries the removal, so retiring it must be the change that lands. This bead owns the real UI -> Messaging request surface; the Messaging Service already has Service.ReloadChannel (internal/app/archiemessaging/channel_status.go:44) and the status surface already carries ReloadSupported.archie's PRD is ready -- awaiting your go/no-go.
PRD — Channel reload request surface (#1474,
archie-core-np7l)Read-only analysis. No build, test or
task checkwas run. Every line reference below was read directly.1. Problem
The Channels page can show channel state and cannot act on it. Five layers of a reload already exist and stop one connection short:
internal/webui/server.go:285instanceOnly+ CSRF/authorization (covered byauthorization_surfaces_test.go:101)internal/webui/api_config.go:48-72s.ReloadChanneland maps any error to 502internal/webui/server.go:63-65ReloadChannel func(context.Context, string) error— assigned nowhere in the treeui/src/lib/api.ts:319-323channelReload— called by no componentinternal/app/archiemessaging/channel_status.go:50-64Service.ReloadChannel, reachable from nothingTwo consequences, both verified:
rg 'srv\.ReloadChannel'finds no assignment;api_config.go:53is the only read.ReloadSupported. The onlychannels.Channelimplementation in production isinternal/infrastructure/channelext.Channel(Name/Start/Stop/ConfigSchema/ValidateConfig).channels.Reloader(internal/channels/channel.go:36-41) has no implementer, sochannelReloadable(channel_status.go:43-46) is false for every channel and the 409 branch is the only one a real request can reach. The bead's first acceptance clause therefore cannot pass by adding a request surface: the channel has to be made reloadable, and that is the larger half of this change.The operator value is concrete: an extension channel's token, allowed users and
show_tool_callslive in extension settings and are read once, inopenExtensionChannels(internal/app/archiemessaging/extension_channels.go:75-160). Rotating a bot token today means restartingarchie-messaging. Extension settings are declaredApplyMode: "live"("each process that supervises extensions re-reads this on its sync tick",internal/infrastructure/controlplanestore/operational_settings.go:60-64) and for channels that is not true — the secret-engine supervisor has a sync tick, channels do not. Org channels are the exception:orgChannelLoop/syncOrgChannels(org_channels.go:60-150) rebuilds them every 30s. So the reload button is the instance's own channels' missing live path.2. Decision: which surface
Recommended: one
ReloadChannelRPC onmessaging.v1.MessagingService, called synchronously by the UI process. Do not build the stored request queue the bead describes.The bead specifies a request the service "observes and clears", which means a new State Store table, 2–3
StatusServiceRPCs, astorecontractinterface and a poll loop. Durability only buys delivery across Messaging Service downtime, and that case is worthless:openExtensionChannelscomposes channels at startup from freshly resolved settings and secrets, so anything queued across a restart is stale by construction. The UI process already holds aMessagingServiceconnection (internal/app/archieui/logs.go:29,messagingrpc.Dial(opts.Messaging.Target, ...), target always resolved —internal/app/archieui/config.go:130-133),messaging.v1is the contract for "the process that holds the channel transports", and the RPC needs no table, migration, config field or poller.ChannelStatus(proto/state/v1/status.proto:53-70) stays untouched, so the bead's own constraint — writer stays the service, shape unchanged — holds exactly.An RPC also keeps the semantics the operator needs and a queue cannot express cheaply: reload returns once the replacement is serving or has failed, with the channel's own reason.
3. Proposed solution
3.1 Contract —
proto/messaging/v1/messaging.proto, alongsideDeliver:Regenerate with
task proto:generate. Request naming satisfiesbuf lint(STANDARD).3.2 Transport —
internal/infrastructure/messagingrpc/messagingrpc.go: aReloaderinterface (ReloadChannel(ctx, id) error), added toRegisterServer(one call site,archiemessaging/run.go:123), a handler mapping sentinels to codes (ErrNoChannel→NotFound, newErrNotReloadableand a failed start→FailedPrecondition, elseInternal), andClient.ReloadChannel. The package has no tests today; add one for the code mapping.3.3 Service —
internal/app/archiemessaging: replace thechannels.Reloadertype assertion with an instance-level rebuild, because a channel cannot restart itself. Only the supervisor can start a replacement (setChannelState,supervise.go:250-276);Reload()= cancelling the run context would park the channel atnextPark(supervise.go:86-95), not restart it.compose.go:channelInstancegainsreload func(context.Context) (channels.Channel, error), nil = not reloadable.extension_channels.go: extract the settings read fromopenExtensionChannelsinto a factory method that re-readssource.Enabled(ctx), re-checksMissingSettings, re-injectsshow_tool_callsfroms.currentConfig(), resolves_refsecrets (buildExtensionChannel, lines 174-214) and builds. Set it as each instance'sreload. Use it for startup too, so there is one path, not two.supervise.go/channel_status.go:Service.ReloadChannelbecomes build-then-setChannelState-then-wait, reusingawaitChannelActivewith a reload-specific deadline (the 5schannelApplyTimeoutis too short for materialise + plugin launch); on failure return the channel's statusDetail, and leave the running channel alone when the build fails.channelReloadable(instance)becomesinstance.reload != nil && instance.current() != nil;channels.Reloaderis deleted (no implementer, no caller).supervise.go:298:Declare(id, true, c.reload != nil).No
channelextchange and nochannel.v1change are needed:extension.Host.Startalready kills a process running under the same name ("so Start is also how a changed binary or setting takes effect",internal/infrastructure/extension/host.go:93-95), so a rebuild+restart is the reload.3.4 Status detail fix (required) —
internal/channels/status/status.go:113-123only overwritesDetailwhen the new value is non-empty, so a"Missing token_ref"detail survives a laterMarkRunning. Reload makes that path reachable: the button would show a running channel with a missing-settings message. ClearDetailon transitions to starting/running/stopped; onlyfailedcarries a reason.3.5 UI process —
internal/app/archieui/logs.go:17-35: the messaging client is already dialled there; setsrv.ReloadChannel = messaging.ReloadChannel(or hoist the dial and pass the client to both wires). No new config, no new process boundary (cmd/archie-ui/architecture_test.gois unaffected).3.6 Dashboard handler —
internal/webui/api_config.go:68-71: map codes instead of blanket 502 —NotFound→404,FailedPrecondition→409 with the server's text as the body (api.tserrorMessagealready surfaces plain-text bodies), else 502. Keep the existing snapshot pre-check at 409; the RPC check is the race-safe second net.3.7 UI —
ui/src/settings/ExtensionChannelSettings.vue: a Reload button beside Save, shown only whenstatus.reload_supported, disabled while in flight, emittingreloadedsoChannelSettingsPage.vuerefetches/api/channels; failures render the body text (e.g.channel "telegram" failed to start: 401 Unauthorized). The page's localChannelStatusinterfaces (ChannelSettingsPage.vue:73-77,ChannelsPage.vue:40-44) gainreload_supported?: boolean.ChannelsPage.vue(the org page) is out of scope — org channels self-reconcile.3.8 Retire the third seam — delete
ChatService.ReloadChannel(proto/gateway/v1/chat.proto:35, 304-307),gatewayrpc.Catalog.ReloadChanneland its server/client methods (catalog.go:52, 128-136), and the "deliberately left unwired" comment (archieui/compose.go:174-176). The gateway builds aCatalogwithout it (archiegateway/catalog.go:28-33), so it always answersUnavailable("this gateway hosts no channels")and nobody serves it.proto/buf.yamlalready ignoresRPC_NO_DELETE/MESSAGE_NO_DELETEforgateway/v1/chat.proto; deleting the two messages will additionally needgateway/v1/chat.protounderPACKAGE_MESSAGE_NO_DELETE(the comment there explains why that rule fires instead), so expect a one-linebuf.yamladdition with a reason.4. Files and components affected
Changes:
proto/messaging/v1/messaging.proto;internal/contracts/messaging/v1/*.pb.go(generated);internal/infrastructure/messagingrpc/messagingrpc.go;internal/app/archiemessaging/{channel_status.go,compose.go,extension_channels.go,supervise.go,run.go};internal/channels/channel.go(deleteReloader);internal/channels/status/status.go;internal/app/archieui/{logs.go,compose.go};internal/webui/api_config.go;ui/src/settings/{ExtensionChannelSettings.vue,ChannelSettingsPage.vue};CHANGELOG.md(+task news).Removals:
proto/gateway/v1/chat.proto:35,304-307;internal/contracts/gateway/v1/chat*.pb.go(regenerated);internal/infrastructure/gatewayrpc/catalog.go:52,128-136;proto/buf.yamlignore list (+1 entry).Untouched on purpose:
proto/state/v1/status.protoandinternal/domain/storecontract/status.go(the status contract's shape),channelext,proto/channel/v1/channel.proto,webuiroutes/authorization.5. Acceptance criteria
POST /api/channels/telegram/reloadreturns 200 for a channel the service reportsreload_supported: true, and the channel comes back running with the newly saved extension settings and re-resolved secrets (rotate the token in Extension settings, click Reload, confirm the old token is refused and the new one is accepted) — noarchie-messagingrestart.reload_supported: falseis refused with 409 and a reason; an unknown id with 404; a failed reload with 409 carrying the channel's own error text. No path returns 501.reload_supportedis true exactly when the instance has a reload seam, and the 409 pre-check cannot disagree with the RPC.setChannelStatebetween runs).status.gofix).ChannelStatusis byte-for-byte unchanged in shape; the service remains its only writer.gateway.v1.ChatServiceno longer declaresReloadChannel;task proto:generate && go build ./... && go vet ./... && go test ./internal/app/archiemessaging ./internal/webui ./internal/infrastructure/messagingrpcpass, andtask newsleavesdocs/news/releases.jsonconsistent withCHANGELOG.md.6. Non-goals
StatusServiceRPC, no table, migration or poller.reconcileOncekeeps carrying onlyshow_tool_calls.acme/telegram) are not reloadable in this change;syncOrgChannelsalready re-reads their settings every 30s.channels.Channel,channelext, or thechannel.v1extension protocol.MessagingService; it is mTLS process identity, asDeliveris. The authority check staysinstanceOnly+authorizeTaskMutation.docs/architecture/migration-decisions.md. It does not exist (docs/ holdsprds/,news/,security/,guides/), and the rationale this bead relies on already lives in theChannelStatuscomments (status.proto:53-60,storecontract/status.go:50-53); the new surface's rationale goes in themessaging.protocomment. The three stale citations (status.proto:13,storecontract/status.go,CHANGELOG.md:1450) are left alone.7. Risks
reconcileLoop'sshow_tool_callsapply; the rebuild readscurrentConfig()so the rebuilt channel carries the latest value.8. Open questions (all together, with recommendations)
channels.Reloader? Recommend yes — nothing implements it and nothing will, because a channel cannot restart itself.channel-settings(agent,allowed_user_ids) on reload? Recommend no: for the system org those live in extension settings (migrated there bycontrolplanestore/telegram_connection.go), so re-reading extension settings is the whole job; channel-settings' chat-level fields are applied live or need the Gateway.extension-settings: live. It would auto-apply settings edits likeorgChannelLoopdoes for orgs, at the cost of restarting bots without a click. Worth its own issue; the reload button is the smaller step that makes the declared apply mode honest on demand.9. Estimated diff size
messaging)messagingrpc)archiemessaging)extension_channels.go, ~45 reload path, −50 dead assertion)channels,status)archieui)webui)buf.yamlreload_test.go,api_config_test.go,messagingrpcmapping)CHANGELOG.mdNet ≈ +400 lines across ~24 files: ~250 hand-written production code, ~170 tests, ~190 generated. With the gateway-seam deletion deferred: ≈ +575 changed lines (it is net-negative). Without tests: ~230 hand-written.
This exceeds AGENTS' "grows past about 100 lines, stop and assess" guidance, and the assessment should be explicit: the new mechanism is one RPC method plus one
reloadfunc field; everything else is connecting surfaces that already exist, moving one settings read into a reusable path, and deleting a dead one. The alternative that stays under 100 lines does not exist — the bead's first acceptance clause needs the channel itself to become reloadable.Decide in chat or on the dashboard.