Channel reload request surface: the UI asks the Messaging Service to reload a channel #1474

Open
opened 2026-10-27 13:40:32 +00:00 by sam · 2 comments
Owner

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

  • PutChannelStatus / ListChannelStatus carry channel state from the Messaging Service to the dashboard, following the config-snapshot split in the contract PRD (grouped table group 51).
  • The store replaces the reported set, so a channel the reporter stops mentioning is deleted rather than left as a stale running.
  • webui.RemoteChannelStatus is the reader; Server.Channels is a source rather than a concrete manager.
  • Reload currently answers 501: there is no backing seam.

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-21

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 - PutChannelStatus / ListChannelStatus carry channel state from the Messaging Service to the dashboard, following the config-snapshot split in the contract PRD (grouped table group 51). - The store replaces the reported set, so a channel the reporter stops mentioning is deleted rather than left as a stale running. - webui.RemoteChannelStatus is the reader; Server.Channels is a source rather than a concrete manager. - Reload currently answers 501: there is no backing seam. 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-21_
sam added the mediumfeature labels 2026-10-27 13:40:32 +00:00
sam self-assigned this 2026-10-27 13:40:32 +00:00
Author
Owner

sam 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 (commit 9bb20830) 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.

_sam 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 (commit 9bb20830) 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.
sam added a new dependency 2026-10-27 13:42:24 +00:00
Author
Owner

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 check was 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:

Layer Location State
HTTP route internal/webui/server.go:285 registered, instanceOnly + CSRF/authorization (covered by authorization_surfaces_test.go:101)
Handler internal/webui/api_config.go:48-72 refuses a non-reloadable channel with 409, a nil seam with 501, otherwise calls s.ReloadChannel and maps any error to 502
Seam internal/webui/server.go:63-65 ReloadChannel func(context.Context, string) error — assigned nowhere in the tree
UI call ui/src/lib/api.ts:319-323 channelReload — called by no component
Service internal/app/archiemessaging/channel_status.go:50-64 Service.ReloadChannel, reachable from nothing

Two consequences, both verified:

  1. The route answers 501 in every deployment. rg 'srv\.ReloadChannel' finds no assignment; api_config.go:53 is the only read.
  2. No production channel can even declare ReloadSupported. The only channels.Channel implementation in production is internal/infrastructure/channelext.Channel (Name/Start/Stop/ConfigSchema/ValidateConfig). channels.Reloader (internal/channels/channel.go:36-41) has no implementer, so channelReloadable (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_calls live in extension settings and are read once, in openExtensionChannels (internal/app/archiemessaging/extension_channels.go:75-160). Rotating a bot token today means restarting archie-messaging. Extension settings are declared ApplyMode: "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 ReloadChannel RPC on messaging.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 StatusService RPCs, a storecontract interface and a poll loop. Durability only buys delivery across Messaging Service downtime, and that case is worthless: openExtensionChannels composes channels at startup from freshly resolved settings and secrets, so anything queued across a restart is stale by construction. The UI process already holds a MessagingService connection (internal/app/archieui/logs.go:29, messagingrpc.Dial(opts.Messaging.Target, ...), target always resolved — internal/app/archieui/config.go:130-133), messaging.v1 is 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, alongside Deliver:

// ReloadChannel asks this process, which holds the channel transports, to
// re-read one channel's settings and secrets and restart it in place. It is a
// request, not state: nothing is stored, so a reload nobody was listening for
// is simply not done. NOT_FOUND: no channel of that id here.
// FAILED_PRECONDITION: the channel is not reloadable, or it did not come back
// (the reason is the message).
rpc ReloadChannel(ReloadChannelRequest) returns (ReloadChannelResponse);
message ReloadChannelRequest { string channel_id = 1; }
message ReloadChannelResponse {}

Regenerate with task proto:generate. Request naming satisfies buf lint (STANDARD).

3.2 Transport — internal/infrastructure/messagingrpc/messagingrpc.go: a Reloader interface (ReloadChannel(ctx, id) error), added to RegisterServer (one call site, archiemessaging/run.go:123), a handler mapping sentinels to codes (ErrNoChannel→NotFound, new ErrNotReloadable and a failed start→FailedPrecondition, else Internal), and Client.ReloadChannel. The package has no tests today; add one for the code mapping.

3.3 Service — internal/app/archiemessaging: replace the channels.Reloader type 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 at nextPark (supervise.go:86-95), not restart it.

  • compose.go: channelInstance gains reload func(context.Context) (channels.Channel, error), nil = not reloadable.
  • extension_channels.go: extract the settings read from openExtensionChannels into a factory method that re-reads source.Enabled(ctx), re-checks MissingSettings, re-injects show_tool_calls from s.currentConfig(), resolves _ref secrets (buildExtensionChannel, lines 174-214) and builds. Set it as each instance's reload. Use it for startup too, so there is one path, not two.
  • supervise.go / channel_status.go: Service.ReloadChannel becomes build-then-setChannelState-then-wait, reusing awaitChannelActive with a reload-specific deadline (the 5s channelApplyTimeout is too short for materialise + plugin launch); on failure return the channel's status Detail, and leave the running channel alone when the build fails. channelReloadable(instance) becomes instance.reload != nil && instance.current() != nil; channels.Reloader is deleted (no implementer, no caller).
  • supervise.go:298: Declare(id, true, c.reload != nil).

No channelext change and no channel.v1 change are needed: extension.Host.Start already 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-123 only overwrites Detail when the new value is non-empty, so a "Missing token_ref" detail survives a later MarkRunning. Reload makes that path reachable: the button would show a running channel with a missing-settings message. Clear Detail on transitions to starting/running/stopped; only failed carries a reason.

3.5 UI process — internal/app/archieui/logs.go:17-35: the messaging client is already dialled there; set srv.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.go is 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.ts errorMessage already 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 when status.reload_supported, disabled while in flight, emitting reloaded so ChannelSettingsPage.vue refetches /api/channels; failures render the body text (e.g. channel "telegram" failed to start: 401 Unauthorized). The page's local ChannelStatus interfaces (ChannelSettingsPage.vue:73-77, ChannelsPage.vue:40-44) gain reload_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.ReloadChannel and its server/client methods (catalog.go:52, 128-136), and the "deliberately left unwired" comment (archieui/compose.go:174-176). The gateway builds a Catalog without it (archiegateway/catalog.go:28-33), so it always answers Unavailable("this gateway hosts no channels") and nobody serves it. proto/buf.yaml already ignores RPC_NO_DELETE/MESSAGE_NO_DELETE for gateway/v1/chat.proto; deleting the two messages will additionally need gateway/v1/chat.proto under PACKAGE_MESSAGE_NO_DELETE (the comment there explains why that rule fires instead), so expect a one-line buf.yaml addition 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 (delete Reloader); 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.yaml ignore list (+1 entry).

Untouched on purpose: proto/state/v1/status.proto and internal/domain/storecontract/status.go (the status contract's shape), channelext, proto/channel/v1/channel.proto, webui routes/authorization.

5. Acceptance criteria

  1. Against a running stack, POST /api/channels/telegram/reload returns 200 for a channel the service reports reload_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) — no archie-messaging restart.
  2. A channel the service reports reload_supported: false is 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.
  3. The capability and the action stay one fact: reload_supported is true exactly when the instance has a reload seam, and the 409 pre-check cannot disagree with the RPC.
  4. A reload that cannot build (settings still missing) fails with the missing-settings reason and leaves any running channel untouched.
  5. A reload of a channel parked after repeated startup failure starts it again (the supervisor is woken, setChannelState between runs).
  6. After a successful reload the status row shows the state with an empty detail — no stale "Missing …" (the status.go fix).
  7. ChannelStatus is byte-for-byte unchanged in shape; the service remains its only writer.
  8. gateway.v1.ChatService no longer declares ReloadChannel; task proto:generate && go build ./... && go vet ./... && go test ./internal/app/archiemessaging ./internal/webui ./internal/infrastructure/messagingrpc pass, and task news leaves docs/news/releases.json consistent with CHANGELOG.md.

6. Non-goals

  • No stored reload request, no StatusService RPC, no table, migration or poller.
  • No gating on, or auto-apply of, channel-settings beyond what a reload re-reads; reconcileOnce keeps carrying only show_tool_calls.
  • Org channels (acme/telegram) are not reloadable in this change; syncOrgChannels already re-reads their settings every 30s.
  • No change to channels.Channel, channelext, or the channel.v1 extension protocol.
  • No new authentication layer on MessagingService; it is mTLS process identity, as Deliver is. The authority check stays instanceOnly + authorizeTaskMutation.
  • No creation of docs/architecture/migration-decisions.md. It does not exist (docs/ holds prds/, news/, security/, guides/), and the rationale this bead relies on already lives in the ChannelStatus comments (status.proto:53-60, storecontract/status.go:50-53); the new surface's rationale goes in the messaging.proto comment. The three stale citations (status.proto:13, storecontract/status.go, CHANGELOG.md:1450) are left alone.
  • No retry, cancellation or progress reporting for a reload.

7. Risks

  • Reload restarts a live bot: in-flight turns are cut. Intended, but the button label should say "Restart and re-read settings"-equivalent, not imply sessions survive.
  • If the reload deadline is shorter than plugin materialise+launch, a reload can report failure while the channel goes on to start. Hence the reload-specific deadline and "still starting" wording rather than a false failure.
  • A reload races reconcileLoop's show_tool_calls apply; the rebuild reads currentConfig() so the rebuilt channel carries the latest value.
  • Not verified: that a Telegram/email extension in practice benefits end to end (blocked-token rotation, new token accepted). The channel extensions live outside this tree; I could not confirm a restart re-reads rotated secrets against a real bot. Verification requires a running stack with a real channel package installed.

8. Open questions (all together, with recommendations)

  1. Surface — messaging RPC (recommended) or the bead's stored request queue? Recommend the RPC: same acceptance, ~1/3 the diff, no stale queue after a restart.
  2. Delete the gateway seam now? Recommend yes, in this change; it is ~180 changed lines, ~150 of them generated, and skipping it buys nothing but a lingering lie in two protos. If the reviewer wants the narrowest first landing, this is the piece to defer.
  3. Delete channels.Reloader? Recommend yes — nothing implements it and nothing will, because a channel cannot restart itself.
  4. Should the instance's channel also re-read channel-settings (agent, allowed_user_ids) on reload? Recommend no: for the system org those live in extension settings (migrated there by controlplanestore/telegram_connection.go), so re-reading extension settings is the whole job; channel-settings' chat-level fields are applied live or need the Gateway.
  5. Follow-up (not started, not in this bead): a channel sync tick — the missing other half of extension-settings: live. It would auto-apply settings edits like orgChannelLoop does 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

Area Files Changed lines (approx.)
Contract + generated (messaging) 3 +100
Transport (messagingrpc) 1 +45
Service (archiemessaging) 5 ±180 (+55/−15 in extension_channels.go, ~45 reload path, −50 dead assertion)
Domain (channels, status) 2 ±10
UI process (archieui) 2 ±6
Dashboard handler (webui) 1 +18
Retired gateway seam + buf.yaml 5 −175
UI (Vue) 3 +34
Tests (reload_test.go, api_config_test.go, messagingrpc mapping) 3 +170
CHANGELOG.md 1 +8

Net ≈ +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 reload func 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.

**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 check` was 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: | Layer | Location | State | |---|---|---| | HTTP route | `internal/webui/server.go:285` | registered, `instanceOnly` + CSRF/authorization (covered by `authorization_surfaces_test.go:101`) | | Handler | `internal/webui/api_config.go:48-72` | refuses a non-reloadable channel with 409, a nil seam with 501, otherwise calls `s.ReloadChannel` and maps any error to 502 | | Seam | `internal/webui/server.go:63-65` | `ReloadChannel func(context.Context, string) error` — **assigned nowhere in the tree** | | UI call | `ui/src/lib/api.ts:319-323` | `channelReload` — called by no component | | Service | `internal/app/archiemessaging/channel_status.go:50-64` | `Service.ReloadChannel`, reachable from nothing | Two consequences, both verified: 1. **The route answers 501 in every deployment.** `rg 'srv\.ReloadChannel'` finds no assignment; `api_config.go:53` is the only read. 2. **No production channel can even declare `ReloadSupported`.** The only `channels.Channel` implementation in production is `internal/infrastructure/channelext.Channel` (Name/Start/Stop/ConfigSchema/ValidateConfig). `channels.Reloader` (`internal/channels/channel.go:36-41`) has no implementer, so `channelReloadable` (`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_calls` live in extension settings and are read once, in `openExtensionChannels` (`internal/app/archiemessaging/extension_channels.go:75-160`). Rotating a bot token today means restarting `archie-messaging`. Extension settings are declared **`ApplyMode: "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 `ReloadChannel` RPC on `messaging.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 `StatusService` RPCs, a `storecontract` interface and a poll loop. Durability only buys delivery across Messaging Service downtime, and that case is worthless: `openExtensionChannels` composes channels at startup from freshly resolved settings and secrets, so anything queued across a restart is stale by construction. The UI process already holds a `MessagingService` connection (`internal/app/archieui/logs.go:29`, `messagingrpc.Dial(opts.Messaging.Target, ...)`, target always resolved — `internal/app/archieui/config.go:130-133`), `messaging.v1` is 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`, alongside `Deliver`: ```proto // ReloadChannel asks this process, which holds the channel transports, to // re-read one channel's settings and secrets and restart it in place. It is a // request, not state: nothing is stored, so a reload nobody was listening for // is simply not done. NOT_FOUND: no channel of that id here. // FAILED_PRECONDITION: the channel is not reloadable, or it did not come back // (the reason is the message). rpc ReloadChannel(ReloadChannelRequest) returns (ReloadChannelResponse); message ReloadChannelRequest { string channel_id = 1; } message ReloadChannelResponse {} ``` Regenerate with `task proto:generate`. Request naming satisfies `buf lint` (STANDARD). **3.2 Transport** — `internal/infrastructure/messagingrpc/messagingrpc.go`: a `Reloader` interface (`ReloadChannel(ctx, id) error`), added to `RegisterServer` (one call site, `archiemessaging/run.go:123`), a handler mapping sentinels to codes (`ErrNoChannel`→`NotFound`, new `ErrNotReloadable` and a failed start→`FailedPrecondition`, else `Internal`), and `Client.ReloadChannel`. The package has no tests today; add one for the code mapping. **3.3 Service** — `internal/app/archiemessaging`: replace the `channels.Reloader` type 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 at `nextPark` (`supervise.go:86-95`), not restart it. - `compose.go`: `channelInstance` gains `reload func(context.Context) (channels.Channel, error)`, nil = not reloadable. - `extension_channels.go`: extract the settings read from `openExtensionChannels` into a factory method that re-reads `source.Enabled(ctx)`, re-checks `MissingSettings`, re-injects `show_tool_calls` from `s.currentConfig()`, resolves `_ref` secrets (`buildExtensionChannel`, lines 174-214) and builds. Set it as each instance's `reload`. Use it for startup too, so there is one path, not two. - `supervise.go` / `channel_status.go`: `Service.ReloadChannel` becomes build-then-`setChannelState`-then-wait, reusing `awaitChannelActive` with a reload-specific deadline (the 5s `channelApplyTimeout` is too short for materialise + plugin launch); on failure return the channel's status `Detail`, and leave the running channel alone when the build fails. `channelReloadable(instance)` becomes `instance.reload != nil && instance.current() != nil`; `channels.Reloader` is deleted (no implementer, no caller). - `supervise.go:298`: `Declare(id, true, c.reload != nil)`. No `channelext` change and no `channel.v1` change are needed: `extension.Host.Start` already 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-123` only overwrites `Detail` when the new value is non-empty, so a `"Missing token_ref"` detail survives a later `MarkRunning`. Reload makes that path reachable: the button would show a running channel with a missing-settings message. Clear `Detail` on transitions to starting/running/stopped; only `failed` carries a reason. **3.5 UI process** — `internal/app/archieui/logs.go:17-35`: the messaging client is already dialled there; set `srv.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.go` is 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.ts` `errorMessage` already 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 when `status.reload_supported`, disabled while in flight, emitting `reloaded` so `ChannelSettingsPage.vue` refetches `/api/channels`; failures render the body text (e.g. `channel "telegram" failed to start: 401 Unauthorized`). The page's local `ChannelStatus` interfaces (`ChannelSettingsPage.vue:73-77`, `ChannelsPage.vue:40-44`) gain `reload_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.ReloadChannel` and its server/client methods (`catalog.go:52, 128-136`), and the "deliberately left unwired" comment (`archieui/compose.go:174-176`). The gateway builds a `Catalog` without it (`archiegateway/catalog.go:28-33`), so it always answers `Unavailable("this gateway hosts no channels")` and nobody serves it. `proto/buf.yaml` already ignores `RPC_NO_DELETE`/`MESSAGE_NO_DELETE` for `gateway/v1/chat.proto`; deleting the two messages will additionally need `gateway/v1/chat.proto` under `PACKAGE_MESSAGE_NO_DELETE` (the comment there explains why that rule fires instead), so expect a one-line `buf.yaml` addition 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` (delete `Reloader`); `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.yaml` ignore list (+1 entry). Untouched on purpose: `proto/state/v1/status.proto` and `internal/domain/storecontract/status.go` (the status contract's shape), `channelext`, `proto/channel/v1/channel.proto`, `webui` routes/authorization. ## 5. Acceptance criteria 1. Against a running stack, `POST /api/channels/telegram/reload` returns 200 for a channel the service reports `reload_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) — **no `archie-messaging` restart**. 2. A channel the service reports `reload_supported: false` is 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. 3. The capability and the action stay one fact: `reload_supported` is true exactly when the instance has a reload seam, and the 409 pre-check cannot disagree with the RPC. 4. A reload that cannot build (settings still missing) fails with the missing-settings reason and leaves any running channel untouched. 5. A reload of a channel parked after repeated startup failure starts it again (the supervisor is woken, `setChannelState` between runs). 6. After a successful reload the status row shows the state with an empty detail — no stale "Missing …" (the `status.go` fix). 7. `ChannelStatus` is byte-for-byte unchanged in shape; the service remains its only writer. 8. `gateway.v1.ChatService` no longer declares `ReloadChannel`; `task proto:generate && go build ./... && go vet ./... && go test ./internal/app/archiemessaging ./internal/webui ./internal/infrastructure/messagingrpc` pass, and `task news` leaves `docs/news/releases.json` consistent with `CHANGELOG.md`. ## 6. Non-goals - No stored reload request, no `StatusService` RPC, no table, migration or poller. - No gating on, or auto-apply of, channel-settings beyond what a reload re-reads; `reconcileOnce` keeps carrying only `show_tool_calls`. - Org channels (`acme/telegram`) are not reloadable in this change; `syncOrgChannels` already re-reads their settings every 30s. - No change to `channels.Channel`, `channelext`, or the `channel.v1` extension protocol. - No new authentication layer on `MessagingService`; it is mTLS process identity, as `Deliver` is. The authority check stays `instanceOnly` + `authorizeTaskMutation`. - No creation of `docs/architecture/migration-decisions.md`. It does not exist (docs/ holds `prds/`, `news/`, `security/`, `guides/`), and the rationale this bead relies on already lives in the `ChannelStatus` comments (`status.proto:53-60`, `storecontract/status.go:50-53`); the new surface's rationale goes in the `messaging.proto` comment. The three stale citations (`status.proto:13`, `storecontract/status.go`, `CHANGELOG.md:1450`) are left alone. - No retry, cancellation or progress reporting for a reload. ## 7. Risks - Reload restarts a live bot: in-flight turns are cut. Intended, but the button label should say "Restart and re-read settings"-equivalent, not imply sessions survive. - If the reload deadline is shorter than plugin materialise+launch, a reload can report failure while the channel goes on to start. Hence the reload-specific deadline and "still starting" wording rather than a false failure. - A reload races `reconcileLoop`'s `show_tool_calls` apply; the rebuild reads `currentConfig()` so the rebuilt channel carries the latest value. - **Not verified:** that a Telegram/email extension in practice benefits end to end (blocked-token rotation, new token accepted). The channel extensions live outside this tree; I could not confirm a restart re-reads rotated secrets against a real bot. Verification requires a running stack with a real channel package installed. ## 8. Open questions (all together, with recommendations) 1. **Surface** — messaging RPC (recommended) or the bead's stored request queue? Recommend the RPC: same acceptance, ~1/3 the diff, no stale queue after a restart. 2. **Delete the gateway seam now?** Recommend yes, in this change; it is ~180 changed lines, ~150 of them generated, and skipping it buys nothing but a lingering lie in two protos. If the reviewer wants the narrowest first landing, this is the piece to defer. 3. **Delete `channels.Reloader`?** Recommend yes — nothing implements it and nothing will, because a channel cannot restart itself. 4. **Should the instance's channel also re-read `channel-settings` (`agent`, `allowed_user_ids`) on reload?** Recommend no: for the system org those live in extension settings (migrated there by `controlplanestore/telegram_connection.go`), so re-reading extension settings is the whole job; channel-settings' chat-level fields are applied live or need the Gateway. 5. **Follow-up (not started, not in this bead):** a channel sync tick — the missing other half of `extension-settings: live`. It would auto-apply settings edits like `orgChannelLoop` does 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 | Area | Files | Changed lines (approx.) | |---|---|---| | Contract + generated (`messaging`) | 3 | +100 | | Transport (`messagingrpc`) | 1 | +45 | | Service (`archiemessaging`) | 5 | ±180 (+55/−15 in `extension_channels.go`, ~45 reload path, −50 dead assertion) | | Domain (`channels`, `status`) | 2 | ±10 | | UI process (`archieui`) | 2 | ±6 | | Dashboard handler (`webui`) | 1 | +18 | | Retired gateway seam + `buf.yaml` | 5 | −175 | | UI (Vue) | 3 | +34 | | Tests (`reload_test.go`, `api_config_test.go`, `messagingrpc` mapping) | 3 | +170 | | `CHANGELOG.md` | 1 | +8 | **Net ≈ +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 `reload` func 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._
sam added the deferred label 2026-11-15 17:26:16 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: sam/archie#1474