dsh-telegram-connector 0.14.1 → 0.15.2

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 0.15.2
+
+- **The Plugins-page configuration page now actually appears and saves.** The
+  three editable fields (`botToken`, `allowedUserIds`, `adminUserId`) are
+  `.volatile()`, so DSH projects the row's settings namespace and passes the
+  `form` object to `plugins.row.config`; without that the Configure page opened
+  with no form. The client bundle now declares the real
+  `@deepseek-ai/dsh-client-ui-plugin-manager` inject, runs every React hook
+  before the loading/unavailable returns, and uses the current
+  `--dsw-alias-*` theme tokens.
+- **Live parameters.** A saved bot token updates the running `TelegramClient`
+  and starts polling if the connector was idle; allowed ids and the admin id
+  are read from the volatile config on every check. The connector now loads
+  with an empty token so the Configure page is reachable, and warns instead of
+  returning early.
+- Tests cover the volatile config shape, the live token path and a rendered
+  ready snapshot.
+
+## 0.15.1
+
+- Release-check fix: the `0.15.0` tag was cut without its COMPATIBILITY row and
+  was never published; this is the published release of the configuration page
+  described below.
+
+## 0.15.0
+
+- **The connector has a configuration page.** On DSH `0.2.1-rc.5` or newer, the
+  Plugins page shows **Configure** on the `dsh-telegram-connector` row: bot
+  token, allowed user ids and admin user id, saved through the page's own form.
+  No `.env` edit or restart is needed; the connector recomposes and starts.
+- **Standalone is a first-class mode.** The setup is optional: the connector
+  does not assume the setup supervisor or updater. The setup-specific commands
+  report the missing sidecar instead of failing; workspaces, sessions, topics,
+  plugins and model calls work on any DSH runtime.
+- The browser half is plain JavaScript in the client-module format, copied to
+  `lib/client.js` by the build; the host half is unchanged.
+
 ## 0.14.1
 
 - **Component actions no longer restart the runtime.** The setup's

package/COMPATIBILITY.md

@@ -6,6 +6,8 @@ every release.
 
 | Connector | DSH | Status | Notes |
 |---|---|---|---|
+| 0.15.2 | `0.2.1-rc.5` | needs UAT | config page fixed: volatile fields expose the form, correct client inject, hooks run before loading returns, DSH theme tokens; saving a token starts polling without a reload |
+| 0.15.1 | `0.2.1-rc.5` | previous | config page attempt; the form stayed hidden because the fields were not volatile and the client inject named a package that does not exist |
 | 0.14.1 | `0.2.1-rc.5` | needs UAT | component actions no longer restart the runtime; the tools load on the next start |
 | 0.14.0 | `0.2.1-rc.5` | needs UAT | one command surface: `/menu` card, `/plugins` subcommands, `/components`; aliases and `/man` removed |
 | 0.13.1 | `0.2.1-rc.5` | needs UAT | `/system status` probes the advertised web address, so a LAN-only bind no longer reports loopback as unreachable |

package/README.md

@@ -141,11 +141,11 @@ Telegram:
 ```sh
 git clone https://github.com/vladtsvirko/dsh-tg-docker-setup
 cd dsh-tg-docker-setup
-./install.sh            # asks for mode, port, bind address, provider, key,
+./setup.sh              # asks for port, bind address, provider, key,
                         # bot token, allowed ids, admin id, git author
 ```
 
-`./install.sh --check` prints the whole plan and changes nothing. The setup
+`./setup.sh --check` prints the whole plan and changes nothing. The setup
 pins a recommended connector tag in its `plugins.json`; the connector is
 versioned on its own and can move to a newer compatible version from the bot without
 a setup release. See [`docs/STANDALONE.md`](docs/STANDALONE.md) for the same
@@ -154,8 +154,7 @@ install without the setup.
 The connector is published to npm as an exact version:
 
 ```sh
-dsh plugin --profile web add dsh-telegram-connector@0.13.1
-export DSH_TELEGRAM_BOT_TOKEN='123456:ABC…'
+dsh plugin --profile web add dsh-telegram-connector@0.15.2
 ```
 
 The registry tarball already contains the built `lib/`, so there is no
@@ -163,6 +162,22 @@ The registry tarball already contains the built `lib/`, so there is no
 the plugin. The setup's `plugins.json` uses the same spec and keeps the GitHub
 tag as a fallback when the registry is unreachable.
 
+### Configure in the UI
+
+On DSH `0.2.1-rc.5` or newer, open **Plugins** → **dsh-telegram-connector** and
+press **Configure** on the `dsh-telegram-connector` row. The page has three
+fields — **bot token**, **allowed user ids** and **admin user id** — and
+**Save** writes the row's config into the profile's user layer. No `.env` edit
+or restart is needed; the connector reconnects with a saved token and starts
+polling, and allowed/admin ids are read on each check.
+
+That is the standalone path: the setup is not required, and the connector does
+not assume the setup's supervisor or updater. Commands that need them
+(`/system update setup`, `/components`, `/firewall allow`, restart/rollback)
+report that the sidecar is unavailable instead of failing. Everything else —
+workspaces, sessions, topics, plugins and model calls — works on any DSH
+runtime.
+
 Installing from the source repository is still possible:
 
 ```sh
@@ -170,7 +185,7 @@ cat >> "$DSH_HOME/profiles/web/pnpm-workspace.yaml" <<'YAML'
 allowBuilds:
   dsh-telegram-connector@https://github.com/vladtsvirko/dsh-telegram-connector.git: true
 YAML
-dsh plugin --profile web add github:vladtsvirko/dsh-telegram-connector#v0.13.1
+dsh plugin --profile web add github:vladtsvirko/dsh-telegram-connector#v0.15.2
 ```
 
 That path runs the package's `prepare` build; pnpm ≥ 10 refuses it until the
@@ -180,6 +195,9 @@ The package is a plugin bundle: `cordis.patch.yml` mounts one row.
 
 ## Configuration
 
+The row config from the UI is the first source. The environment is the
+fallback (the setup writes it; a standalone profile can export it instead):
+
 Environment:
 
 | Variable | Meaning |

package/docs/DESIGN.md

@@ -316,7 +316,9 @@ and directories.
   Commit/Roll back, component Enable/Disable/Port, the update card's **Cancel** and Take
   over all check `adminUserId`. The allowlist only decides who may talk to the
   agent; a button that changes the deployment is an admin action.
-- The bot token comes from the environment, never from `cordis.patch.yml`.
+- The bot token comes from the profile's Plugins config (the environment is the
+  fallback), never from `cordis.patch.yml`. The same applies to the allowlist
+  and admin id.
 - The bot is a group admin and can delete topics: `/dangerous cleanup` requires
   an explicit `confirm`, and `/forget` never deletes anything.
 - Plugin mutations are the highest-risk surface: a bundle's code and install

package/docs/STANDALONE.md

@@ -17,7 +17,7 @@ The same package runs in any DSH profile.
 
 ```sh
 # Published package: the tarball already contains lib/, so no build script.
-dsh plugin --profile web add dsh-telegram-connector@0.13.0
+dsh plugin --profile web add dsh-telegram-connector@0.15.2
 ```
 
 From the source repository instead:
@@ -27,11 +27,16 @@ cat >> "$DSH_HOME/profiles/web/pnpm-workspace.yaml" <<'YAML'
 allowBuilds:
   dsh-telegram-connector@https://github.com/vladtsvirko/dsh-telegram-connector.git: true
 YAML
-dsh plugin --profile web add github:vladtsvirko/dsh-telegram-connector#v0.13.0
+dsh plugin --profile web add github:vladtsvirko/dsh-telegram-connector#v0.15.2
 ```
 
-The bundle patch mounts the `dsh-telegram-connector` row and reads deployment
-values from the environment:
+Open **Plugins** → **dsh-telegram-connector** → **Configure** and fill in the
+bot token, allowed user ids and optional admin id. **Save** stores them in the
+profile's user layer; a saved token starts polling without a runtime restart,
+and the ids are read on every check. No environment file is required.
+
+The bundle patch still reads deployment values from the environment as the
+fallback:
 
 ```sh
 export DSH_TELEGRAM_BOT_TOKEN='123456:ABC…'

package/lib/client.js

@@ -0,0 +1,244 @@
+/**
+ * Browser half: the configuration page for the `dsh-telegram-connector` row.
+ *
+ * DSH's Plugins page declares the `plugins.row.config` slot; this module
+ * registers the row's page with the values a fresh standalone install needs.
+ * The host half reads the same volatile keys from its Config schema; the patch
+ * keeps the environment as the fallback, and a value saved here is the
+ * profile's user layer, which wins over it.
+ */
+window.__ModuleLoader__.load({
+  id: 'dsh-telegram-connector',
+  factory: (require) => {
+    var module = { exports: {} }
+    var exports = module.exports
+    Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
+
+    const React = require('react')
+    const h = React.createElement
+
+    const KEY = 'dsh-telegram-connector#dsh-telegram-connector'
+    const styles = `
+.dsh-telegram-form { display: flex; flex-direction: column; gap: 16px; max-width: 560px; color: var(--dsw-alias-label-primary); font-size: 13px; }
+.dsh-telegram-form .panel { display: flex; flex-direction: column; gap: 4px; padding: 10px 12px; border: 1px solid var(--dsw-alias-border-l1); border-radius: 6px; background: var(--dsw-alias-bg-layer-2); }
+.dsh-telegram-form .row { display: flex; align-items: center; gap: 6px; font-weight: 500; }
+.dsh-telegram-form .dot { flex: none; width: 6px; height: 6px; border-radius: 50%; background: var(--dsw-alias-state-idle-primary); }
+.dsh-telegram-form .dot.ok { background: var(--dsw-alias-state-success-primary); }
+.dsh-telegram-form .muted { color: var(--dsw-alias-label-secondary); font-size: 12px; line-height: 1.45; }
+.dsh-telegram-form .field { display: flex; flex-direction: column; gap: 6px; }
+.dsh-telegram-form .label { font-weight: 500; }
+.dsh-telegram-form .hint { color: var(--dsw-alias-label-secondary); font-size: 12px; line-height: 1.4; }
+.dsh-telegram-form .input { box-sizing: border-box; width: 100%; min-height: 32px; padding: 6px 10px; border: 1px solid var(--dsw-alias-border-l1); border-radius: 6px; background: var(--dsw-alias-bg-layer-1); color: var(--dsw-alias-label-primary); font: inherit; font-size: 13px; }
+.dsh-telegram-form .input:focus { outline: 1px solid var(--dsw-alias-brand-primary); outline-offset: 1px; }
+.dsh-telegram-form .input:disabled { opacity: 0.6; }
+.dsh-telegram-form .actions { display: flex; align-items: center; gap: 10px; }
+.dsh-telegram-form .primary { min-height: 32px; padding: 0 14px; border: 1px solid var(--dsw-alias-border-l2); border-radius: 6px; background: var(--dsw-alias-bg-layer-1); color: var(--dsw-alias-label-primary); font: inherit; font-size: 13px; font-weight: 500; cursor: pointer; }
+.dsh-telegram-form .primary:hover:not(:disabled) { background: var(--dsw-alias-bg-layer-2); }
+.dsh-telegram-form .primary:disabled { opacity: 0.55; cursor: default; }
+.dsh-telegram-form .message { color: var(--dsw-alias-label-secondary); font-size: 12px; }
+`
+
+    function Field({ label, hint, children }) {
+      return h(
+        'label',
+        { className: 'field' },
+        h('span', { className: 'label' }, label),
+        hint === undefined ? null : h('span', { className: 'hint' }, hint),
+        children,
+      )
+    }
+
+    function parseIds(text) {
+      const parts = text.split(/[\s,]+/).map((part) => part.trim()).filter((part) => part.length > 0)
+      const ids = []
+      for (const part of parts) {
+        const id = Number(part)
+        if (!Number.isInteger(id) || id <= 0) return undefined
+        ids.push(id)
+      }
+      return ids
+    }
+
+    function TelegramConfigForm({ form }) {
+      // Every hook runs before any early return: the page transitions through
+      // loading/unavailable snapshots and a conditional hook would crash React.
+      const state = form === undefined ? undefined : form.state
+      const value = (state === undefined ? undefined : state.value) ?? {}
+      const [botToken, setBotToken] = React.useState(String(value.botToken ?? ''))
+      const [allowed, setAllowed] = React.useState(
+        Array.isArray(value.allowedUserIds) ? value.allowedUserIds.join(', ') : '',
+      )
+      const [admin, setAdmin] = React.useState(
+        value.adminUserId === undefined ? '' : String(value.adminUserId),
+      )
+      const [saving, setSaving] = React.useState(false)
+      const [message, setMessage] = React.useState('')
+
+      const revision = state === undefined ? undefined : state.revision
+      React.useEffect(() => {
+        const next = state === undefined ? {} : (state.value ?? {})
+        setBotToken(String(next.botToken ?? ''))
+        setAllowed(Array.isArray(next.allowedUserIds) ? next.allowedUserIds.join(', ') : '')
+        setAdmin(next.adminUserId === undefined ? '' : String(next.adminUserId))
+      }, [revision])
+
+      if (state === undefined) {
+        return h('p', null, 'Loading the configuration…')
+      }
+      if (state.status === 'unavailable') {
+        return h('p', null, 'This plugin is not loaded, so it cannot be configured right now.')
+      }
+      if (state.status === 'loading') {
+        return h('p', null, 'Loading the current values…')
+      }
+
+      const savedToken = String(value.botToken ?? '')
+      const savedAllowed = Array.isArray(value.allowedUserIds) ? value.allowedUserIds : []
+      const savedAdmin = value.adminUserId
+      const tokenSet = savedToken.trim().length > 0
+      const configured = tokenSet && savedAllowed.length > 0
+      const disabled = !state.writable || saving
+      const saved = state.user ?? {}
+      const source = (key) => (Object.prototype.hasOwnProperty.call(saved, key) ? 'saved here' : 'environment fallback')
+
+      const save = async () => {
+        const ids = parseIds(allowed)
+        if (ids === undefined) {
+          setMessage('Allowed user ids must be positive integers, separated by commas or spaces.')
+          return
+        }
+        const adminText = admin.trim()
+        const adminId = adminText.length === 0 ? undefined : Number(adminText)
+        if (adminId !== undefined && (!Number.isInteger(adminId) || adminId <= 0)) {
+          setMessage('The admin user id must be a positive integer, or empty to use the first allowed id.')
+          return
+        }
+        setSaving(true)
+        setMessage('')
+        try {
+          const ops = [
+            { op: 'set', path: ['botToken'], value: botToken.trim() },
+            { op: 'set', path: ['allowedUserIds'], value: ids },
+            adminId === undefined
+              ? { op: 'unset', path: ['adminUserId'] }
+              : { op: 'set', path: ['adminUserId'], value: adminId },
+          ]
+          const ok = await form.mutate(ops, state.revision)
+          if (!ok) {
+            setMessage('The runtime did not accept these values; they were left for you to correct.')
+          } else if (botToken.trim().length === 0 || ids.length === 0) {
+            setMessage('Saved. Set a bot token and at least one allowed user id to start the connector.')
+          } else {
+            setMessage('Saved. The connector uses these values immediately.')
+          }
+        } catch (error) {
+          setMessage(`Save failed: ${String(error)}`)
+        } finally {
+          setSaving(false)
+        }
+      }
+
+      return h(
+        'div',
+        { className: 'dsh-telegram-form' },
+        h('style', null, styles),
+        h(
+          'div',
+          { className: 'panel' },
+          h(
+            'div',
+            { className: 'row' },
+            h('span', { className: configured ? 'dot ok' : 'dot' }),
+            h('span', null, configured ? 'Configured' : 'Not configured yet'),
+          ),
+          h(
+            'div',
+            { className: 'muted' },
+            `Bot token ${tokenSet ? 'set' : 'not set'} · ${savedAllowed.length} allowed user(s) · admin ${savedAdmin === undefined ? 'first allowed' : String(savedAdmin)}`,
+          ),
+          h(
+            'div',
+            { className: 'muted' },
+            `Bot token: ${source('botToken')} · allowed ids: ${source('allowedUserIds')} · admin: ${source('adminUserId')}`,
+          ),
+          h('div', { className: 'muted' }, 'Saving writes this profile and applies without restarting the runtime.'),
+        ),
+        h(
+          Field,
+          {
+            label: 'Bot token',
+            hint: 'The token from @BotFather. It is stored in this profile; avoid screenshots and commits.',
+          },
+          h('input', {
+            type: 'password',
+            className: 'input',
+            value: botToken,
+            disabled,
+            placeholder: '123456789:AA…',
+            onChange: (event) => setBotToken(event.target.value),
+          }),
+        ),
+        h(
+          Field,
+          {
+            label: 'Allowed user ids',
+            hint: 'Numeric Telegram ids, comma or space separated. Everyone here can talk to the agent and use its sessions.',
+          },
+          h('input', {
+            type: 'text',
+            className: 'input',
+            value: allowed,
+            disabled,
+            placeholder: '142283532, 777000111',
+            onChange: (event) => setAllowed(event.target.value),
+          }),
+        ),
+        h(
+          Field,
+          {
+            label: 'Admin user id',
+            hint: 'Optional. One allowed id that may update, restart, roll back and manage plugins; empty uses the first allowed id.',
+          },
+          h('input', {
+            type: 'text',
+            className: 'input',
+            value: admin,
+            disabled,
+            placeholder: 'optional',
+            onChange: (event) => setAdmin(event.target.value),
+          }),
+        ),
+        h(
+          'div',
+          { className: 'actions' },
+          h(
+            'button',
+            {
+              type: 'button',
+              className: 'primary',
+              disabled,
+              onClick: save,
+            },
+            saving ? 'Saving…' : 'Save',
+          ),
+          message.length === 0 ? null : h('span', { className: 'message' }, message),
+        ),
+      )
+    }
+
+    const inject = ['slots']
+    function apply(ctx) {
+      ctx.slots.inject('plugins.row.config', () =>
+        ctx.slots.register(
+          { name: 'plugins.row.config', key: KEY },
+          ({ view, form }) => (view === 'summary' ? null : h(TelegramConfigForm, { form })),
+        ),
+      )
+    }
+
+    exports.NS = 'dsh-telegram-connector'
+    exports.apply = apply
+    exports.inject = inject
+    return module.exports
+  },
+})

package/lib/index.d.ts

@@ -10,54 +10,35 @@
  *
  * @module dsh-telegram-connector
  */
-import type { Context } from '@deepseek-ai/cordis';
+import type { Context, Volatile } from '@deepseek-ai/cordis';
 import Schema from '@deepseek-ai/schemastery';
 export declare const name = "dsh-telegram-connector";
 export declare const inject: string[];
-export declare const Config: Schema<Schemastery.ObjectS<NoInfer<{
-    botToken: Schema<string, string, "defined">;
-    allowedUserIds: Schema<number[], number[], "defined">;
-    adminUserId: Schema<number, number, "plain">;
-    workspaceRoot: Schema<string, string, "defined">;
-    provider: Schema<string, string, "plain">;
-    model: Schema<string, string, "plain">;
-    editIntervalMs: Schema<number, number, "defined">;
-    pollTimeoutSeconds: Schema<number, number, "defined">;
-    /** Deadline for one Bot API call; a hung call must not freeze a topic. */
-    requestTimeoutSeconds: Schema<number, number, "defined">;
-    downloadTimeoutSeconds: Schema<number, number, "defined">;
-    reconcileIntervalSeconds: Schema<number, number, "defined">;
-    processMode: Schema<"off" | "summary" | "live", "off" | "summary" | "live", "defined">;
-    agentPreset: Schema<string, string, "plain">;
-    reactionsEnabled: Schema<boolean, boolean, "defined">;
-    readReaction: Schema<string, string, "defined">;
-    streamingReaction: Schema<string, string, "defined">;
-    stagedReaction: Schema<string, string, "defined">;
-}>>, Schemastery.ObjectT<NoInfer<{
-    botToken: Schema<string, string, "defined">;
-    allowedUserIds: Schema<number[], number[], "defined">;
-    adminUserId: Schema<number, number, "plain">;
-    workspaceRoot: Schema<string, string, "defined">;
-    provider: Schema<string, string, "plain">;
-    model: Schema<string, string, "plain">;
-    editIntervalMs: Schema<number, number, "defined">;
-    pollTimeoutSeconds: Schema<number, number, "defined">;
-    /** Deadline for one Bot API call; a hung call must not freeze a topic. */
-    requestTimeoutSeconds: Schema<number, number, "defined">;
-    downloadTimeoutSeconds: Schema<number, number, "defined">;
-    reconcileIntervalSeconds: Schema<number, number, "defined">;
-    processMode: Schema<"off" | "summary" | "live", "off" | "summary" | "live", "defined">;
-    agentPreset: Schema<string, string, "plain">;
-    reactionsEnabled: Schema<boolean, boolean, "defined">;
-    readReaction: Schema<string, string, "defined">;
-    streamingReaction: Schema<string, string, "defined">;
-    stagedReaction: Schema<string, string, "defined">;
-}>>, "plain">;
+export interface ConnectorConfigInput {
+    botToken?: string;
+    allowedUserIds?: number[];
+    adminUserId?: number;
+    workspaceRoot?: string;
+    provider?: string;
+    model?: string;
+    editIntervalMs?: number;
+    pollTimeoutSeconds?: number;
+    requestTimeoutSeconds?: number;
+    downloadTimeoutSeconds?: number;
+    reconcileIntervalSeconds?: number;
+    processMode?: 'off' | 'summary' | 'live';
+    agentPreset?: string;
+    reactionsEnabled?: boolean;
+    readReaction?: string;
+    streamingReaction?: string;
+    stagedReaction?: string;
+}
+export declare const Config: Schema<ConnectorConfigInput, ConnectorConfig>;
 export interface ConnectorConfig {
-    botToken: string;
-    allowedUserIds: number[];
+    botToken: Volatile<string>;
+    allowedUserIds: Volatile<number[]>;
     /** The one account that may run update/restart/rollback/plugins commands. */
-    adminUserId?: number;
+    adminUserId: Volatile<number | undefined>;
     workspaceRoot?: string;
     provider?: string;
     model?: string;

package/lib/index.js

@@ -41,9 +41,9 @@ import { bindingsPath, findWorkspace, loadBindings, removeSession, saveBindings,
 export const name = 'dsh-telegram-connector';
 export const inject = ['agents', 'sessions'];
 export const Config = Schema.object({
-    botToken: Schema.string().default(''),
-    allowedUserIds: Schema.array(Schema.number()).default([]),
-    adminUserId: Schema.number(),
+    botToken: Schema.string().default('').volatile(),
+    allowedUserIds: Schema.array(Schema.number()).default([]).volatile(),
+    adminUserId: Schema.number().volatile(),
     workspaceRoot: Schema.string().default(''),
     provider: Schema.string(),
     model: Schema.string(),
@@ -101,9 +101,13 @@ function truncate(text, limit) {
     return clean.length <= limit ? clean : `${clean.slice(0, limit - 1)}…`;
 }
 export function apply(ctx, config) {
-    if (config.botToken.length === 0) {
-        ctx.logger.warn('dsh-telegram-connector: botToken is empty; the connector will not start');
-        return;
+    // The three editable fields are volatile: the Plugins page writes them and
+    // this row reads them through get(). Everything else stays ordinary config.
+    const botToken = () => config.botToken.get();
+    const allowedUserIds = () => config.allowedUserIds.get();
+    const adminUserId = () => config.adminUserId.get();
+    if (botToken().trim().length === 0) {
+        ctx.logger.warn('dsh-telegram-connector: botToken is empty; configure it on the Plugins page');
     }
     const agentPresetService = () => {
         const get = ctx.get;
@@ -112,14 +116,14 @@ export function apply(ctx, config) {
     const requestTimeoutMs = Math.max(5, config.requestTimeoutSeconds ?? 60) * 1000;
     const pollTimeoutMs = Math.max(5, config.pollTimeoutSeconds ?? 25) * 1000 + 30_000;
     const downloadTimeoutMs = Math.max(10, config.downloadTimeoutSeconds ?? 120) * 1000;
-    const client = new TelegramClient(config.botToken, { requestTimeoutMs, pollTimeoutMs, downloadTimeoutMs });
+    const client = new TelegramClient(botToken(), { requestTimeoutMs, pollTimeoutMs, downloadTimeoutMs });
     const agents = ctx.agents;
     // Publisher bots are send-only; the main bot stays the only poller. Tokens come
     // from the environment so they never land in the profile patch.
     const publisherTokens = (process.env.DSH_TELEGRAM_PUBLISHER_TOKENS ?? '')
         .split(/[,\s]+/)
         .map((token) => token.trim())
-        .filter((token) => token.length > 0 && token !== config.botToken);
+        .filter((token) => token.length > 0 && token !== botToken());
     const botHandles = [
         { label: 'main', client, main: true },
         ...publisherTokens.map((token, index) => ({
@@ -155,6 +159,10 @@ export function apply(ctx, config) {
     let bindings = { version: 2, workspaces: {}, sessions: {} };
     let offset = 0;
     let stopped = false;
+    /** True after start() finished its one-time setup. */
+    let started = false;
+    /** True while pollLoop owns getUpdates; a token saved later starts it once. */
+    let polling = false;
     let lastErrorAt = 0;
     let reconcileTimer;
     let reconciling = false;
@@ -169,12 +177,12 @@ export function apply(ctx, config) {
     const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
     const updaterToken = process.env.DSH_UPDATER_TOKEN ?? '';
     const updaterUrl = (process.env.DSH_UPDATER_URL ?? 'http://updater:8787').replace(/\/+$/, '');
-    if (config.allowedUserIds.length === 0) {
+    if (allowedUserIds().length === 0) {
         logger.warn('dsh-telegram-connector: allowedUserIds is empty; every message will be refused');
     }
     /** Last error an agent reported, shown by `/system status`. */
     let lastAgentError;
-    const isAllowed = (userId) => userId !== undefined && config.allowedUserIds.includes(userId);
+    const isAllowed = (userId) => userId !== undefined && allowedUserIds().includes(userId);
     /**
      * Who may run profile-global commands (update, restart, rollback, plugins).
      *
@@ -185,8 +193,8 @@ export function apply(ctx, config) {
     const isAdmin = (userId) => {
         if (userId === undefined)
             return false;
-        if (config.adminUserId !== undefined)
-            return userId === config.adminUserId;
+        if (adminUserId() !== undefined)
+            return userId === adminUserId();
         // No admin configured (an upgraded deployment, or one set up by hand): the
         // owner of the control chat is the admin, so an upgrade cannot lock anyone
         // out. In a private chat the chat id *is* the user id.
@@ -202,9 +210,9 @@ export function apply(ctx, config) {
         const sender = message.from?.id;
         if (isAdmin(sender))
             return true;
-        const who = config.adminUserId === undefined
+        const who = adminUserId() === undefined
             ? 'the owner of this chat (`DSH_ADMIN_USER_ID` is not set)'
-            : `admin ${String(config.adminUserId)}`;
+            : `admin ${String(adminUserId())}`;
         void reply(message, `only ${who} can do that — it changes the deployment for everyone.`);
         return false;
     };
@@ -1604,11 +1612,11 @@ export function apply(ctx, config) {
         ].join('\n'));
     };
     /** Who may run profile-global commands, and how that was decided. */
-    const adminLine = () => config.adminUserId === undefined
+    const adminLine = () => adminUserId() === undefined
         ? bindings.controlChatId === undefined
             ? 'admin: any allowed user until the bot chat is used (set `DSH_ADMIN_USER_ID` to name one)'
             : 'admin: the owner of this chat (set `DSH_ADMIN_USER_ID` to name one explicitly)'
-        : `admin: ${String(config.adminUserId)}`;
+        : `admin: ${String(adminUserId())}`;
     /** The provider key this deployment is supposed to have. */
     const providerKeyNames = () => {
         const declared = (process.env.DSH_PROVIDER_API_KEY_ENV ?? '').trim();
@@ -5284,6 +5292,14 @@ export function apply(ctx, config) {
                 stderr(`${bot.label}: member of ${stats.present}/${total} bound group(s)`);
         }
     };
+    const ensurePolling = () => {
+        if (!started || polling || stopped || botToken().trim().length === 0)
+            return;
+        polling = true;
+        void pollLoop().finally(() => {
+            polling = false;
+        });
+    };
     const start = async () => {
         // A file that could not be read is set aside by the loader; say so in the
         // chat, once, instead of letting the bot answer "not attached" forever.
@@ -5353,7 +5369,13 @@ export function apply(ctx, config) {
             await sendTo(chat, 0, `the runtime's workspace registry did not list ${String(healed.restored)} workspace(s) / ${String(healed.attached)} session(s) that Telegram still had — they are back, and the web UI lists them again.`, 'control');
         })
             .catch((error) => stderr(`registry repair failed: ${String(error)}`));
-        void pollLoop();
+        started = true;
+        if (botToken().trim().length === 0) {
+            stderr('not configured: set the bot token on the Plugins page; polling starts when it is saved');
+        }
+        else {
+            ensurePolling();
+        }
         void announceTrial();
         void flushBridgeTurns().catch((error) => stderr(`bridge flush failed: ${String(error)}`));
         void replayBridgeInputs().catch((error) => stderr(`bridge replay failed: ${String(error)}`));
@@ -5732,6 +5754,22 @@ export function apply(ctx, config) {
             return;
         }
     });
+    // A volatile-only config commit updates the running fiber in place; it does
+    // not reload this plugin. Follow the values that affect the long-lived bot:
+    // a new token changes the client and starts polling if it was idle.
+    ctx.on('loader/volatile-update', (paths) => {
+        const touched = (field) => paths.some((path) => path[path.length - 1] === field);
+        if (touched('botToken')) {
+            const next = botToken().trim();
+            client.setToken(next);
+            stderr(next.length > 0 ? 'bot token updated; polling with the new token' : 'bot token cleared; polling will fail until one is set');
+            ensurePolling();
+        }
+        if (touched('allowedUserIds'))
+            stderr(`allowed users updated (${String(allowedUserIds().length)})`);
+        if (touched('adminUserId'))
+            stderr(`admin updated (${adminUserId() === undefined ? 'first allowed user' : String(adminUserId())})`);
+    });
     ctx.effect(() => {
         void start();
         return () => {