@goodandready/dsh-messenger-gateway 0.4.43 → 0.4.45

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -154,6 +154,7 @@ In addition to Telegram, outbound messages can be dispatched to Discord and Slac
154
154
  - Delivered updates are deduplicated across polling and webhook transports and the poll offset survives restarts — commands never execute twice
155
155
  - Artifact SVG entering the dashboard store is sanitized (script blocks, event handlers and `javascript:` URLs stripped)
156
156
  - Pending interactive asks are bounded (200 concurrent) and the ask timeout is clamped to 10 minutes
157
+ - Long replies are chunked by raw markdown (fence-aware) so no HTML tag is ever cut at a message boundary; `/voice summary` and `/keyboard` persist through the settings writer
157
158
  - `telegram.apiRoot` with plain `http` is only accepted for loopback hosts (a local Bot API server); the webhook URL is logged without its secret path
158
159
  - `webhooks.enabled: false` removes the messenger write routes entirely; GET `/update` and `/messenger` require trusted callers
159
160
  - `webAppEnabled: false` takes the whole Mini App surface down (dashboard and every `/api/*` answer 404) and clears the menu button
@@ -161,6 +162,8 @@ In addition to Telegram, outbound messages can be dispatched to Discord and Slac
161
162
  - Note: turn replies to the user are streamed directly and are not covered by the outbox retry guarantee (by design — streaming edits cannot be replayed)
162
163
  - Inline keyboard `replyMarkup` sent via `/messenger/send` is schema-validated (button text/actions, sizes) before delivery
163
164
  - All state files (pairing, outbox, voice prefs) are written with `0600` permissions inside `0700` directories
165
+ - State persistence is durable and versioned: every write is fsynced before the rename (directory fsynced after), each save keeps a `.bak` of the previous good version, files carry a `schemaVersion` with migrations from legacy formats, and a corrupted file is preserved as `.corrupt-<ts>` and recovered from `.bak` — pairing never silently wipes access (fail-closed with an explicit error)
166
+ - Config sync is granular: changes that do not touch the transport slice (tokens, proxy, Bot API root, poll/webhook mode, adapter enablement, session scope) are applied live on the running gateway — active dialogs, streaming replies, pending asks and the Telegram polling offset survive a settings save; only transport changes recreate the gateway, and recreation is serialized (single-flight)
164
167
  - `sessionList`: `true` (default) — enables `/sessions` and `/resume` commands in chat
165
168
  - `sessionTitleFromChat`: `false` (default) — name each new session after its originating chat (`TG · @user`, `TG · Group › topic N`) instead of generic generated titles
166
169
  - `voiceMode`: `mirror` / `always` / `off` — when to speak replies (also `/voice`)
package/README.ru.md CHANGED
@@ -100,6 +100,7 @@ graph LR
100
100
  * Белые списки разрешенных ID (`allowedUserIds`);
101
101
  * Команды `/get` и `/files` доступны только пользователям из белого списка и никогда не отдают скрытые файлы (dotfiles, например `.env`);
102
102
  * Loopback-запросы доверяются только с закреплёнными Host (`localhost` / `127.0.0.1` / `[::1]`) — защита от DNS rebinding; для доверенного локального reverse-proxy есть явный флаг `security.trustProxy`.
103
+ * Живучесть состояния: записи состояния атомарны с fsync, версионированы (`schemaVersion` + миграции), каждая запись хранит `.bak` прошлой версии, повреждённый файл сохраняется как `.corrupt-*` и восстанавливается из `.bak` — доступ никогда не обнуляется молча (fail-closed + явная ошибка);
103
104
 
104
105
  ### 6. 🤖 Команды бота (`commands.js`)
105
106
  * `/start` — приветствие и запуск сопряжения;
package/README.zh.md CHANGED
@@ -86,6 +86,7 @@ dsh plugin --profile web add @goodandready/dsh-messenger-gateway
86
86
  - **默认关闭白名单模式(`allowlistMode: closed`,fail-closed)**:全新安装不会响应任何用户,直到管理员批准配对码;`open` 模式(空列表时放行所有人)必须显式开启,仅适用于公共助手机器人;
87
87
  - `/get` 与 `/files` 命令仅对白名单用户可用,且永远不会返回隐藏文件(dotfiles,如 `.env`);
88
88
  - 本地回环请求只接受固定的 Host(`localhost` / `127.0.0.1` / `[::1]`)— 防 DNS Rebinding;如需在受信任的本地反向代理后使用,可显式开启 `security.trustProxy`。
89
+ - 持久化状态:写入先 fsync 再原子重命名,文件带 `schemaVersion`(旧格式自动迁移),每次保存保留 `.bak`,损坏文件以 `.corrupt-*` 保留并可从 `.bak` 恢复——绝不静默清空访问(fail-closed + 显式错误);
89
90
 
90
91
  ---
91
92
 
@@ -7,7 +7,7 @@ import {
7
7
  cacheName,
8
8
  extOf, saveToCache, safeName, TELEGRAM_MAX_DOC_BYTES,
9
9
  } from '../media.js'
10
- import { splitText } from '../text.js'
10
+ import { splitText, splitMarkdownForTelegram } from '../text.js'
11
11
  import { prepareTelegramText } from '../telegram-format.js'
12
12
  import { normalizeTelegramCommands } from '../commands.js'
13
13
  import { normalizeThreadId, telegramThreadParams } from '../topics.js'
@@ -42,8 +42,6 @@ export class TelegramAdapter {
42
42
  constructor(opts) {
43
43
  this.name = 'telegram'
44
44
  this.token = String(opts.botToken || '').trim()
45
- this.allowedUserIds = (opts.allowedUserIds || []).map(Number).filter((n) => Number.isFinite(n))
46
- this.allowlistMode = opts.allowlistMode === 'open' ? 'open' : 'closed'
47
45
  this.timeoutSeconds = Number(opts.timeoutSeconds) || 50
48
46
  this.pollIntervalMs = Number(opts.pollIntervalMs) || 500
49
47
  this.media = opts.media || {}
@@ -53,17 +51,6 @@ export class TelegramAdapter {
53
51
  this.onUnauthorized = opts.onUnauthorized
54
52
  this.isUserAllowed = opts.isUserAllowed
55
53
  this.logger = opts.logger
56
- this.commands = normalizeTelegramCommands(opts.commands)
57
- this.textFormat = opts.textFormat === 'plain' ? 'plain' : 'html'
58
- this.groupsEnabled = opts.groupsEnabled !== false
59
- this.groupRequireMention = opts.groupRequireMention !== false
60
- this.reactionsEnabled = opts.reactionsEnabled !== false
61
- this.quickActions = opts.quickActions === true
62
- this.artifactPreviews = opts.artifactPreviews !== false
63
- this.transport = opts.transport === 'webhook' ? 'webhook' : 'poll'
64
- this.statusIndicator = opts.statusIndicator === true
65
- this.statusOnline = String(opts.statusOnline || 'Online')
66
- this.statusOffline = String(opts.statusOffline || 'Offline')
67
54
  this.sendRetryMax = 2
68
55
  this.sendRetryBaseMs = 400
69
56
  this.pollingConflict = false
@@ -71,6 +58,7 @@ export class TelegramAdapter {
71
58
  this.webhookUrl = String(opts.webhookUrl || '').trim()
72
59
  this.webhookSecret = String(opts.webhookSecret || '').trim()
73
60
  this.stopped = false
61
+ this.transport = opts.transport === 'webhook' ? 'webhook' : 'poll'
74
62
  this.mediaGroups = new Map()
75
63
  this.mediaGroupDebounceMs = Number(opts.mediaGroupDebounceMs) || 650
76
64
  this.pollTimer = undefined
@@ -94,6 +82,30 @@ export class TelegramAdapter {
94
82
  this.apiFetch = fetch
95
83
  this.logger?.error?.(`dsh-messenger-gateway: telegram proxy is invalid, using direct connection: ${err.message}`)
96
84
  }
85
+ // Non-transport options (#224) are snapshotted through the same helper a
86
+ // live config update uses, so constructor and applyLiveConfig cannot drift.
87
+ this.applyLiveConfig(opts)
88
+ }
89
+
90
+ /**
91
+ * Re-snapshot NON-transport options from a new telegram config section
92
+ * (#224). Transport-critical fields (token, proxy, apiRoot, transport,
93
+ * webhook URL/secret, poll intervals) require a gateway restart and are
94
+ * deliberately ignored here.
95
+ */
96
+ applyLiveConfig(tg = {}) {
97
+ this.allowedUserIds = (tg.allowedUserIds || []).map(Number).filter((n) => Number.isFinite(n))
98
+ this.allowlistMode = tg.allowlistMode === 'open' ? 'open' : 'closed'
99
+ this.commands = normalizeTelegramCommands(tg.commands)
100
+ this.textFormat = tg.textFormat === 'plain' ? 'plain' : 'html'
101
+ this.groupsEnabled = tg.groupsEnabled !== false
102
+ this.groupRequireMention = tg.groupRequireMention !== false
103
+ this.reactionsEnabled = tg.reactionsEnabled !== false
104
+ this.quickActions = tg.quickActions === true
105
+ this.artifactPreviews = tg.artifactPreviews !== false
106
+ this.statusIndicator = tg.statusIndicator === true
107
+ this.statusOnline = String(tg.statusOnline || 'Online')
108
+ this.statusOffline = String(tg.statusOffline || 'Offline')
97
109
  }
98
110
 
99
111
  setAllowedUserIds(ids) {
@@ -784,19 +796,25 @@ export class TelegramAdapter {
784
796
  }
785
797
 
786
798
  async sendFormattedMessage(chatId, replyTo, text, payload, threadId, replyMarkup) {
787
- const { text: formatted, parseMode } = this.formatOutgoingText(text, payload)
788
- const chunks = splitText(formatted, TELEGRAM_MAX)
789
- const plainChunks = splitText(text, TELEGRAM_MAX)
790
799
  const effectiveMarkup = replyMarkup !== undefined
791
800
  ? replyMarkup
792
801
  : (this.quickActions && !threadId
793
802
  ? buildQuickActionsKeyboard(this.webAppUrl)
794
803
  : (!threadId ? REMOVE_REPLY_KEYBOARD : undefined))
795
- for (let i = 0; i < chunks.length; i++) {
804
+ // Chunk the RAW markdown so that every Telegram message carries complete,
805
+ // unclosed-tag-free HTML (#229): splitting after the HTML conversion could
806
+ // cut a tag at the chunk boundary.
807
+ const rawChunks = splitMarkdownForTelegram(
808
+ text,
809
+ TELEGRAM_MAX,
810
+ (s) => this.formatOutgoingText(s, payload).text,
811
+ )
812
+ for (let i = 0; i < rawChunks.length; i++) {
813
+ const { text: formatted, parseMode } = this.formatOutgoingText(rawChunks[i], payload)
796
814
  const params = {
797
815
  chat_id: chatId,
798
- text: chunks[i],
799
- reply_to_message_id: replyTo,
816
+ text: formatted,
817
+ reply_to_message_id: i === 0 ? replyTo : undefined,
800
818
  reply_markup: i === 0 ? effectiveMarkup : undefined,
801
819
  ...telegramThreadParams(threadId),
802
820
  }
@@ -816,8 +834,8 @@ export class TelegramAdapter {
816
834
  try {
817
835
  await this.call('sendMessage', {
818
836
  chat_id: chatId,
819
- text: plainChunks[i] ?? chunks[i],
820
- reply_to_message_id: replyTo,
837
+ text: rawChunks[i],
838
+ reply_to_message_id: i === 0 ? replyTo : undefined,
821
839
  reply_markup: i === 0 ? effectiveMarkup : undefined,
822
840
  ...telegramThreadParams(threadId),
823
841
  })
@@ -826,7 +844,7 @@ export class TelegramAdapter {
826
844
  this.logger?.warn?.(`telegram plain send topic gone (thread ${threadId}), fallback main chat: ${err2.message}`)
827
845
  await this.call('sendMessage', {
828
846
  chat_id: chatId,
829
- text: plainChunks[i] ?? chunks[i],
847
+ text: rawChunks[i],
830
848
  reply_to_message_id: replyTo,
831
849
  reply_markup: i === 0 ? effectiveMarkup : undefined,
832
850
  })
package/lib/config.js CHANGED
@@ -141,6 +141,34 @@ export const PluginConfig = z.object({
141
141
 
142
142
  export const Config = PluginConfig
143
143
 
144
+ /**
145
+ * Transport-critical config slice (#224): adapters snapshot their options
146
+ * when the gateway starts, so a change in ANY of these fields requires a
147
+ * full gateway recreation. Everything else (tts, agent model/cwd, homes,
148
+ * allowlist, quick actions, security…) is applied live on the running
149
+ * gateway — an active dialog, streaming replies, pending asks and the
150
+ * Telegram polling offset are preserved.
151
+ */
152
+ export function transportSignatureOf(cfg) {
153
+ return JSON.stringify({
154
+ enabled: cfg?.enabled,
155
+ sessionScope: cfg?.agent?.sessionScope,
156
+ telegram: {
157
+ enabled: cfg?.telegram?.enabled,
158
+ botToken: cfg?.telegram?.botToken,
159
+ proxyUrl: cfg?.telegram?.proxyUrl,
160
+ apiRoot: cfg?.telegram?.apiRoot,
161
+ transport: cfg?.telegram?.transport,
162
+ webhookUrl: cfg?.telegram?.webhookUrl,
163
+ webhookSecret: cfg?.telegram?.webhookSecret,
164
+ pollIntervalMs: cfg?.telegram?.pollIntervalMs,
165
+ timeoutSeconds: cfg?.telegram?.timeoutSeconds,
166
+ },
167
+ discord: { enabled: cfg?.discord?.enabled, botToken: cfg?.discord?.botToken, webhookUrl: cfg?.discord?.webhookUrl },
168
+ slack: { enabled: cfg?.slack?.enabled, botToken: cfg?.slack?.botToken, webhookUrl: cfg?.slack?.webhookUrl },
169
+ })
170
+ }
171
+
144
172
  // Unwrap Volatile boxes before any caller reads a value. The Loader mutates the
145
173
  // boxes in place and re-announces them with loader/volatile-update, so this must
146
174
  // read the entry config lazily rather than caching the parsed result.
@@ -862,9 +862,15 @@ export async function handleGatewayCommand(gw, key, text, input) {
862
862
  if (sub === 'summary') {
863
863
  const val = parts[2]?.toLowerCase()
864
864
  if (val === 'on' || val === 'off') {
865
+ const on = val === 'on'
865
866
  if (!gw.config.tts) gw.config.tts = {}
866
- gw.config.tts.voiceSummary = val === 'on'
867
- return reply(`Voice summary (TL;DR): ${val === 'on' ? 'enabled' : 'disabled'}`)
867
+ gw.config.tts.voiceSummary = on
868
+ // Persist through the settings writer (#222) so /voice summary
869
+ // survives config syncs and /config reports the live state.
870
+ gw.hooks?.persistVoiceSummary?.(on).catch((e) => {
871
+ gw.logger?.debug?.('persistVoiceSummary:', e?.message || e)
872
+ })
873
+ return reply(`Voice summary (TL;DR): ${on ? 'enabled' : 'disabled'}`)
868
874
  }
869
875
  const state = gw.config.tts?.voiceSummary ? 'on' : 'off'
870
876
  return reply(`Voice summary (TL;DR): ${state}\nToggle: <code>/voice summary on|off</code>`)
@@ -940,12 +946,20 @@ export async function handleGatewayCommand(gw, key, text, input) {
940
946
  const tgAdapter = gw.getAdapter('telegram')
941
947
  if (sub === 'on') {
942
948
  if (tgAdapter) tgAdapter.quickActions = true
949
+ // Persist through the settings writer (#222) so /keyboard on|off
950
+ // survives config syncs and /config reports the live state.
951
+ gw.hooks?.persistQuickActions?.(true)?.catch((e) => {
952
+ gw.logger?.debug?.('persistQuickActions:', e?.message || e)
953
+ })
943
954
  return reply('Quick action keyboard enabled.', {
944
955
  replyMarkup: buildQuickActionsKeyboard(),
945
956
  })
946
957
  }
947
958
  if (sub === 'off') {
948
959
  if (tgAdapter) tgAdapter.quickActions = false
960
+ gw.hooks?.persistQuickActions?.(false)?.catch((e) => {
961
+ gw.logger?.debug?.('persistQuickActions:', e?.message || e)
962
+ })
949
963
  return reply('Quick action keyboard disabled.', {
950
964
  replyMarkup: REMOVE_REPLY_KEYBOARD,
951
965
  })
package/lib/gateway.js CHANGED
@@ -401,6 +401,20 @@ export class Gateway {
401
401
  this.callbackIndex.clear()
402
402
  }
403
403
 
404
+ /**
405
+ * Live config swap without gateway recreation (#224). Callers (index.js
406
+ * sync) only route here when the transport-critical slice is unchanged, so
407
+ * polling, active chats and pending asks survive; adapters that snapshot
408
+ * safe options re-apply them from the matching config section.
409
+ */
410
+ applyConfig(next) {
411
+ this.config = next
412
+ for (const adapter of this.adapterList) {
413
+ const section = next?.[adapter.name]
414
+ if (section && typeof adapter.applyLiveConfig === 'function') adapter.applyLiveConfig(section)
415
+ }
416
+ }
417
+
404
418
  getAdapter(platform) { return this.adapters.get(platform) }
405
419
 
406
420
  async sendToMessenger(target, payload, opts = {}) {
package/lib/index.js CHANGED
@@ -12,7 +12,7 @@ import {
12
12
  } from './messenger-api.js'
13
13
  import { listHomes } from './homes.js'
14
14
  export { plainConfig } from './config.js'
15
- import { Config, plainConfig, resolveInternalBaseUrl } from './config.js'
15
+ import { Config, plainConfig, resolveInternalBaseUrl, transportSignatureOf } from './config.js'
16
16
  import { describeProxy, maskProxyUrl } from './proxy.js'
17
17
  import { readSecrets, restoreSecrets } from './secret-guard.js'
18
18
  import { setupSettings } from './settings-bridge.js'
@@ -249,56 +249,117 @@ export function apply(ctx, config) {
249
249
  })
250
250
  }
251
251
 
252
- let lastSyncSignature
253
- const sync = () => {
254
- syncWebhookRoute()
255
- const effective = source()
256
- // DSH sends several events for one settings write, and restarting the gateway
257
- // drops live sessions and resets the Telegram polling offset. Restart only
258
- // when the resolved config actually changed.
259
- let signature
260
- try { signature = JSON.stringify(effective) } catch { signature = undefined }
261
- if (gateway && signature !== undefined && signature === lastSyncSignature) return
262
- lastSyncSignature = signature
263
- guardSecrets(effective).catch((err) => ctx.logger?.warn?.(`dsh-messenger-gateway: secret guard failed: ${err?.message || err}`))
264
- if (gateway) { gateway.stop(); gateway = undefined }
265
- if (effective.enabled === false) return
266
- gateway = new Gateway(ctx, effective, {
267
- persistAllowedUserIds: async (ids) => {
268
- if (!settingsApi?.isReady?.()) return
252
+ // Gateway hooks are static: they read the CURRENT config at execution time
253
+ // through the settings writer mutex, so they can be created once (#224).
254
+ const gatewayHooks = {
255
+ persistAllowedUserIds: async (ids) => {
256
+ if (!settingsApi?.isReady?.()) return
257
+ await settingsApi.writeExclusive(async (api) => {
269
258
  const cur = source()
270
- await settingsApi.replace(Config({
259
+ await api.replace(Config({
271
260
  ...cur,
272
261
  telegram: { ...cur.telegram, allowedUserIds: ids },
273
262
  }))
274
- },
275
- persistHome: async ({ chatId, threadId }) => {
276
- if (!settingsApi?.isReady?.()) throw new Error('settings not ready')
263
+ })
264
+ },
265
+ persistHome: async ({ chatId, threadId }) => {
266
+ if (!settingsApi?.isReady?.()) throw new Error('settings not ready')
267
+ await settingsApi.writeExclusive(async (api) => {
277
268
  const cur = source()
278
- await settingsApi.replace(Config({
269
+ await api.replace(Config({
279
270
  ...cur,
280
271
  telegram: { ...cur.telegram, homeChatId: chatId, homeThreadId: threadId || 0 },
281
272
  }))
282
- },
283
- persistHomes: async (nextTelegram) => {
284
- if (!settingsApi?.isReady?.()) throw new Error('settings not ready')
273
+ })
274
+ },
275
+ persistHomes: async (nextTelegram) => {
276
+ if (!settingsApi?.isReady?.()) throw new Error('settings not ready')
277
+ await settingsApi.writeExclusive(async (api) => {
285
278
  const cur = source()
286
- await settingsApi.replace(Config({
279
+ await api.replace(Config({
287
280
  ...cur,
288
281
  telegram: { ...cur.telegram, ...nextTelegram },
289
282
  }))
290
- },
291
- persistAgentModel: async ({ provider, model }) => {
292
- if (!settingsApi?.isReady?.()) return
283
+ })
284
+ },
285
+ persistAgentModel: async ({ provider, model }) => {
286
+ if (!settingsApi?.isReady?.()) return
287
+ await settingsApi.writeExclusive(async (api) => {
293
288
  const cur = source()
294
- await settingsApi.replace(Config({
289
+ await api.replace(Config({
295
290
  ...cur,
296
291
  agent: { ...cur.agent, provider, model },
297
292
  }))
298
- },
299
- })
293
+ })
294
+ },
295
+ // Runtime toggles from chat commands (#222): /voice summary and
296
+ // /keyboard on|off now survive config syncs like every other writer.
297
+ persistVoiceSummary: async (on) => {
298
+ if (!settingsApi?.isReady?.()) return
299
+ await settingsApi.writeExclusive(async (api) => {
300
+ const cur = source()
301
+ await api.replace(Config({
302
+ ...cur,
303
+ tts: { ...cur.tts, voiceSummary: on },
304
+ }))
305
+ })
306
+ },
307
+ persistQuickActions: async (on) => {
308
+ if (!settingsApi?.isReady?.()) return
309
+ await settingsApi.writeExclusive(async (api) => {
310
+ const cur = source()
311
+ await api.replace(Config({
312
+ ...cur,
313
+ telegram: { ...cur.telegram, quickActions: on },
314
+ }))
315
+ })
316
+ },
317
+ }
318
+
319
+ let lastSyncSignature
320
+ let lastTransportSignature
321
+ let syncChain = Promise.resolve()
322
+ const startGateway = (cfg) => {
323
+ gateway = new Gateway(ctx, cfg, gatewayHooks)
300
324
  gateway.start().catch((err) => ctx.logger?.warn?.(`dsh-messenger-gateway: ${err.message}`))
301
325
  }
326
+ const sync = () => {
327
+ syncWebhookRoute()
328
+ const effective = source()
329
+ // DSH sends several events for one settings write; skip identical repeats.
330
+ let signature
331
+ try { signature = JSON.stringify(effective) } catch { signature = undefined }
332
+ if (gateway && signature !== undefined && signature === lastSyncSignature) return
333
+ lastSyncSignature = signature
334
+ guardSecrets(effective).catch((err) => ctx.logger?.warn?.(`dsh-messenger-gateway: secret guard failed: ${err?.message || err}`))
335
+ // Granular apply (#224): when the transport-critical slice is unchanged,
336
+ // swap the config on the LIVE gateway instead of tearing it down.
337
+ const transportSig = transportSignatureOf(effective)
338
+ if (gateway && transportSig === lastTransportSignature) {
339
+ gateway.applyConfig(effective)
340
+ return
341
+ }
342
+ lastTransportSignature = transportSig
343
+ if (effective.enabled === false) {
344
+ // Serialize even the shutdown path so it cannot interleave with a
345
+ // queued restart (#224).
346
+ const run = syncChain.then(async () => {
347
+ if (gateway) { await gateway.stop(); gateway = undefined }
348
+ })
349
+ syncChain = run.catch((err) => { ctx.logger?.debug?.('dsh-messenger-gateway: sync stop error:', err?.message || err) })
350
+ return
351
+ }
352
+ // Serialize gateway recreation: concurrent sync events queue their
353
+ // stop()/start() cycles instead of racing (#224). The queued run reads
354
+ // source() at execution time, so the last config always wins.
355
+ const run = syncChain.then(async () => {
356
+ const cfg = source()
357
+ if (gateway) { await gateway.stop(); gateway = undefined }
358
+ startGateway(cfg)
359
+ })
360
+ syncChain = run.catch((err) => { ctx.logger?.debug?.('dsh-messenger-gateway: sync restart error:', err?.message || err) })
361
+ return run
362
+ }
302
363
 
303
364
  const settingsBridge = setupSettings(ctx, {
304
365
  namespace: SETTINGS_NAMESPACE,
@@ -321,6 +382,11 @@ export function apply(ctx, config) {
321
382
  if (!api) throw new Error('settings not ready')
322
383
  return api.update(patch)
323
384
  },
385
+ writeExclusive: (fn) => {
386
+ const api = settingsBridge.getSettingsApi()
387
+ if (!api) throw new Error('settings not ready')
388
+ return api.writeExclusive(fn)
389
+ },
324
390
  isReady: () => Boolean(settingsBridge.getSettingsApi()),
325
391
  }
326
392
 
@@ -690,37 +756,41 @@ export function apply(ctx, config) {
690
756
  let payload = parsedConfig.data
691
757
  if (payload && typeof payload.config === 'object') payload = payload.config
692
758
  try {
693
- const cur = source()
694
- const nextTg = { ...cur.telegram, ...(payload.telegram || {}) }
695
- if (payload.telegram && !String(payload.telegram.botToken || '').trim()) nextTg.botToken = cur.telegram.botToken
696
- // proxyUrl is a secret: empty value or an echoed mask means "keep the
697
- // stored proxy" (#200)
698
- if (payload.telegram && Object.prototype.hasOwnProperty.call(payload.telegram, 'proxyUrl')) {
699
- const incoming = String(payload.telegram.proxyUrl || '').trim()
700
- if (!incoming || incoming.includes(':***@') || incoming === maskProxyUrl(cur.telegram.proxyUrl || '')) {
701
- nextTg.proxyUrl = cur.telegram.proxyUrl
759
+ // Serialized through the settings write mutex (#221): concurrent PUT
760
+ // /config and chat-command persists no longer lose updates.
761
+ await settingsApi.writeExclusive(async (api) => {
762
+ const cur = source()
763
+ const nextTg = { ...cur.telegram, ...(payload.telegram || {}) }
764
+ if (payload.telegram && !String(payload.telegram.botToken || '').trim()) nextTg.botToken = cur.telegram.botToken
765
+ // proxyUrl is a secret: empty value or an echoed mask means "keep the
766
+ // stored proxy" (#200)
767
+ if (payload.telegram && Object.prototype.hasOwnProperty.call(payload.telegram, 'proxyUrl')) {
768
+ const incoming = String(payload.telegram.proxyUrl || '').trim()
769
+ if (!incoming || incoming.includes(':***@') || incoming === maskProxyUrl(cur.telegram.proxyUrl || '')) {
770
+ nextTg.proxyUrl = cur.telegram.proxyUrl
771
+ }
702
772
  }
703
- }
704
- if (payload.telegram && Object.prototype.hasOwnProperty.call(payload.telegram, 'webhookSecret') && !String(payload.telegram.webhookSecret || '').trim()) {
705
- nextTg.webhookSecret = cur.telegram.webhookSecret
706
- }
707
- if (payload.telegram?.notifyBridge) {
708
- nextTg.notifyBridge = { ...cur.telegram.notifyBridge, ...payload.telegram.notifyBridge }
709
- }
710
- const nextDiscord = { ...(cur.discord || {}), ...(payload.discord || {}) }
711
- if (payload.discord && !String(payload.discord.botToken || '').trim()) nextDiscord.botToken = cur.discord?.botToken
712
- const nextSlack = { ...(cur.slack || {}), ...(payload.slack || {}) }
713
- if (payload.slack && !String(payload.slack.botToken || '').trim()) nextSlack.botToken = cur.slack?.botToken
714
- await settingsApi.replace(Config({
715
- ...cur,
716
- ...payload,
717
- telegram: nextTg,
718
- discord: nextDiscord,
719
- slack: nextSlack,
720
- tts: { ...cur.tts, ...(payload.tts || {}) },
721
- agent: { ...cur.agent, ...(payload.agent || {}) },
722
- media: { ...cur.media, ...(payload.media || {}) },
723
- }))
773
+ if (payload.telegram && Object.prototype.hasOwnProperty.call(payload.telegram, 'webhookSecret') && !String(payload.telegram.webhookSecret || '').trim()) {
774
+ nextTg.webhookSecret = cur.telegram.webhookSecret
775
+ }
776
+ if (payload.telegram?.notifyBridge) {
777
+ nextTg.notifyBridge = { ...cur.telegram.notifyBridge, ...payload.telegram.notifyBridge }
778
+ }
779
+ const nextDiscord = { ...(cur.discord || {}), ...(payload.discord || {}) }
780
+ if (payload.discord && !String(payload.discord.botToken || '').trim()) nextDiscord.botToken = cur.discord?.botToken
781
+ const nextSlack = { ...(cur.slack || {}), ...(payload.slack || {}) }
782
+ if (payload.slack && !String(payload.slack.botToken || '').trim()) nextSlack.botToken = cur.slack?.botToken
783
+ await api.replace(Config({
784
+ ...cur,
785
+ ...payload,
786
+ telegram: nextTg,
787
+ discord: nextDiscord,
788
+ slack: nextSlack,
789
+ tts: { ...cur.tts, ...(payload.tts || {}) },
790
+ agent: { ...cur.agent, ...(payload.agent || {}) },
791
+ media: { ...cur.media, ...(payload.media || {}) },
792
+ }))
793
+ })
724
794
  sync()
725
795
  writeJson(res, 200, { ok: true, config: publicConfig(source(), getGw(), ctx) })
726
796
  } catch (err) {
package/lib/outbox.js CHANGED
@@ -26,6 +26,7 @@ import { writeJsonAtomic } from './storage-atomic.js'
26
26
  import { isTopicGoneError } from './telegram-errors.js'
27
27
 
28
28
  const LOCK_STALE_MS = 30_000
29
+ const OUTBOX_SCHEMA_VERSION = 1
29
30
 
30
31
  /**
31
32
  * Exclusive lock file scoped to the queue (#218). Returns false when another
@@ -164,7 +165,9 @@ export function createOutboxQueue(options = {}) {
164
165
 
165
166
  async function persist() {
166
167
  try {
167
- await writeJsonAtomic(storagePath, { pending, dlq })
168
+ // schemaVersion envelope (#227): future format changes migrate instead
169
+ // of misreading; readers stay tolerant of legacy files without it.
170
+ await writeJsonAtomic(storagePath, { schemaVersion: OUTBOX_SCHEMA_VERSION, pending, dlq })
168
171
  } catch (err) {
169
172
  if (logger) {
170
173
  logger.warn?.(`[outbox] failed to persist queue to disk: ${err.message}`)
package/lib/pairing.js CHANGED
@@ -1,8 +1,8 @@
1
- import { randomBytes, randomUUID } from 'node:crypto'
2
- import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync, unlinkSync } from 'node:fs'
3
- import { dirname } from 'node:path'
1
+ import { randomBytes } from 'node:crypto'
2
+ import { writeJsonAtomicSync, readJsonStateSync, StateCorruptError } from './storage-atomic.js'
4
3
 
5
4
  const ALPHABET = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789'
5
+ const PAIRING_SCHEMA_VERSION = 1
6
6
 
7
7
  export function generatePairingCode(length = 8) {
8
8
  const bytes = randomBytes(length)
@@ -11,35 +11,50 @@ export function generatePairingCode(length = 8) {
11
11
  return out
12
12
  }
13
13
 
14
- function writeJsonAtomicSync(filePath, data) {
15
- const dir = dirname(filePath)
16
- mkdirSync(dir, { recursive: true, mode: 0o700 })
17
- const tmpPath = `${filePath}.${randomUUID().slice(0, 8)}.tmp`
18
- try {
19
- writeFileSync(tmpPath, JSON.stringify(data, null, 2), { encoding: 'utf8', mode: 0o600 })
20
- renameSync(tmpPath, filePath)
21
- } catch (err) {
22
- try { unlinkSync(tmpPath) } catch { /* safe best-effort temp file cleanup */ }
23
- throw err
24
- }
14
+ const migratePairing = (raw) => ({
15
+ schemaVersion: PAIRING_SCHEMA_VERSION,
16
+ approved: Array.isArray(raw?.approved) ? raw.approved : [],
17
+ pending: raw?.pending && typeof raw.pending === 'object' ? raw.pending : {},
18
+ })
19
+
20
+ const logLoadFailure = (logger, err) => {
21
+ const detail = err instanceof StateCorruptError
22
+ ? `state file corrupted and unrecoverable; access stays fail-closed (empty allowlist); corrupted copy preserved at ${err.corruptBackup || 'an unknown path'}`
23
+ : `read error: ${err?.message || err}`
24
+ const message = `[dsh-messenger-gateway] pairing store ${detail}`
25
+ if (typeof logger?.error === 'function') logger.error(message)
26
+ else logger?.warn?.(message)
25
27
  }
26
28
 
27
29
  /** @param {string} filePath @param {any} [opts] */
28
30
  export function createPairingStore(filePath, { logger } = {}) {
29
31
  const state = { pending: {}, /** @type {number[]} */ approved: [] }
30
- if (filePath && existsSync(filePath)) {
32
+ if (filePath) {
31
33
  try {
32
- const raw = JSON.parse(readFileSync(filePath, 'utf8'))
33
- if (Array.isArray(raw.approved)) state.approved = raw.approved.map(Number).filter(Number.isFinite)
34
- if (raw.pending && typeof raw.pending === 'object') state.pending = raw.pending
34
+ const { data, recovered, corruptBackup } = readJsonStateSync(filePath, {
35
+ version: PAIRING_SCHEMA_VERSION,
36
+ migrate: migratePairing,
37
+ })
38
+ if (data) {
39
+ state.approved = (data.approved || []).map(Number).filter(Number.isFinite)
40
+ state.pending = data.pending && typeof data.pending === 'object' ? data.pending : {}
41
+ }
42
+ if (recovered) {
43
+ logger?.warn?.(`[dsh-messenger-gateway] pairing store recovered from .bak after corruption; preserved copy: ${corruptBackup}`)
44
+ }
35
45
  } catch (err) {
36
- logger?.warn?.('[dsh-messenger-gateway] pairing store read error:', err?.message || err)
46
+ if (err instanceof StateCorruptError || err?.name === 'StateVersionError') logLoadFailure(logger, err)
47
+ else logger?.warn?.('[dsh-messenger-gateway] pairing store read error:', err?.message || err)
37
48
  }
38
49
  }
39
50
  const persist = () => {
40
51
  if (!filePath) return
41
52
  try {
42
- writeJsonAtomicSync(filePath, { approved: state.approved, pending: state.pending })
53
+ writeJsonAtomicSync(filePath, {
54
+ schemaVersion: PAIRING_SCHEMA_VERSION,
55
+ approved: state.approved,
56
+ pending: state.pending,
57
+ })
43
58
  } catch (err) {
44
59
  logger?.warn?.('[dsh-messenger-gateway] pairing store persist error:', err?.message || err)
45
60
  }
package/lib/personas.js CHANGED
@@ -1,5 +1,4 @@
1
- import { readFileSync } from 'node:fs'
2
- import { writeJsonAtomicSync } from './storage-atomic.js'
1
+ import { writeJsonAtomicSync, readJsonStateSync, StateCorruptError } from './storage-atomic.js'
3
2
 
4
3
  export const BUILTIN_PERSONAS = {
5
4
  default: {
@@ -70,25 +69,42 @@ export function listPersonas() {
70
69
  return Object.values(BUILTIN_PERSONAS)
71
70
  }
72
71
 
72
+ const PERSONAS_SCHEMA_VERSION = 1
73
+
74
+ // Legacy files either carried {personas, presets} at the top level or a bare
75
+ // persona map; v1 wraps everything under a versioned envelope (#227).
76
+ const migratePersonas = (raw) => {
77
+ if (raw && typeof raw === 'object' && (raw.personas || raw.presets)) {
78
+ return { schemaVersion: PERSONAS_SCHEMA_VERSION, personas: raw.personas || {}, presets: raw.presets || {} }
79
+ }
80
+ return { schemaVersion: PERSONAS_SCHEMA_VERSION, personas: (raw && typeof raw === 'object') ? raw : {}, presets: {} }
81
+ }
82
+
73
83
  /** @param {string} filePath @param {any} [opts] */
74
84
  export function createPersonaStore(filePath, { logger } = {}) {
75
85
  let cache = { personas: {}, presets: {} }
76
86
  try {
77
- const raw = JSON.parse(readFileSync(filePath, 'utf8'))
78
- if (raw && typeof raw === 'object') {
79
- if (raw.personas || raw.presets) {
80
- cache = { personas: raw.personas || {}, presets: raw.presets || {} }
81
- } else {
82
- cache = { personas: raw, presets: {} }
83
- }
87
+ const { data, recovered, corruptBackup } = readJsonStateSync(filePath, {
88
+ version: PERSONAS_SCHEMA_VERSION,
89
+ migrate: migratePersonas,
90
+ })
91
+ if (data) cache = { personas: data.personas || {}, presets: data.presets || {} }
92
+ if (recovered) {
93
+ logger?.warn?.(`[dsh-messenger-gateway] personas store recovered from .bak after corruption; preserved copy: ${corruptBackup}`)
84
94
  }
85
95
  } catch (err) {
86
- if (err?.code !== 'ENOENT') logger?.warn?.('[dsh-messenger-gateway] personas load error:', err?.message || err)
96
+ if (err instanceof StateCorruptError || err?.name === 'StateVersionError') {
97
+ const message = `[dsh-messenger-gateway] personas store corrupted; starting empty; corrupted copy preserved at ${err.corruptBackup || filePath}`
98
+ if (typeof logger?.error === 'function') logger.error(message)
99
+ else logger?.warn?.(message)
100
+ } else if (err?.code !== 'ENOENT') {
101
+ logger?.warn?.('[dsh-messenger-gateway] personas load error:', err?.message || err)
102
+ }
87
103
  }
88
104
 
89
105
  function save() {
90
106
  try {
91
- writeJsonAtomicSync(filePath, cache)
107
+ writeJsonAtomicSync(filePath, { schemaVersion: PERSONAS_SCHEMA_VERSION, ...cache })
92
108
  } catch (err) {
93
109
  logger?.warn?.('[dsh-messenger-gateway] personas save error:', err?.message || err)
94
110
  }
package/lib/scheduler.js CHANGED
@@ -1,6 +1,7 @@
1
- import { readFile } from 'node:fs/promises'
2
1
  import { randomUUID } from 'node:crypto'
3
- import { writeJsonAtomic } from './storage-atomic.js'
2
+ import { writeJsonAtomic, readJsonStateSync, StateCorruptError } from './storage-atomic.js'
3
+
4
+ const SCHEDULER_SCHEMA_VERSION = 1
4
5
 
5
6
  export function parseRelativeTime(input) {
6
7
  if (!input) return null
@@ -39,18 +40,36 @@ export function createScheduler(filePath, onDue, options = {}) {
39
40
  let loaded = false
40
41
  let timer = null
41
42
 
43
+ // Legacy files were a bare task array; v1 adds the schema envelope (#227).
44
+ // A `null` tasks value marks a legacy payload that was never a task array:
45
+ // load() reports it with the historic "invalid tasks payload" warning.
46
+ const migrateScheduler = (raw) => ({
47
+ schemaVersion: SCHEDULER_SCHEMA_VERSION,
48
+ tasks: Array.isArray(raw) ? raw : (Array.isArray(raw?.tasks) ? raw.tasks : null),
49
+ })
50
+
42
51
  async function load() {
43
52
  try {
44
- const raw = await readFile(filePath, 'utf8')
45
- const parsed = JSON.parse(raw)
46
- if (Array.isArray(parsed)) {
47
- tasks = parsed
48
- } else {
49
- logger?.warn?.(`[dsh-messenger-gateway] scheduler invalid tasks payload in ${filePath}: expected array, got ${typeof parsed}; resetting to empty list`)
50
- tasks = []
53
+ const { data, recovered, corruptBackup } = readJsonStateSync(filePath, {
54
+ version: SCHEDULER_SCHEMA_VERSION,
55
+ migrate: migrateScheduler,
56
+ })
57
+ if (data) {
58
+ if (Array.isArray(data.tasks)) tasks = data.tasks
59
+ else {
60
+ logger?.warn?.(`[dsh-messenger-gateway] scheduler invalid tasks payload in ${filePath}: expected array, got ${typeof data.tasks}; resetting to empty list`)
61
+ tasks = []
62
+ }
63
+ }
64
+ if (recovered) {
65
+ logger?.warn?.(`[dsh-messenger-gateway] scheduler recovered from .bak after corruption; preserved copy: ${corruptBackup}`)
51
66
  }
52
67
  } catch (err) {
53
- if (err?.code !== 'ENOENT') {
68
+ if (err instanceof StateCorruptError || err?.name === 'StateVersionError') {
69
+ const message = `[dsh-messenger-gateway] scheduler state corrupted; reminders lost unless a preserved copy is restored manually; corrupted file kept at ${err.corruptBackup || filePath}`
70
+ if (typeof logger?.error === 'function') logger.error(message)
71
+ else logger?.warn?.(message)
72
+ } else if (err?.code !== 'ENOENT') {
54
73
  logger?.warn?.('[dsh-messenger-gateway] scheduler load error:', err?.message || err)
55
74
  }
56
75
  tasks = []
@@ -70,7 +89,7 @@ export function createScheduler(filePath, onDue, options = {}) {
70
89
  const finishTime = t.firedAt || t.createdAt || 0
71
90
  return (now - finishTime) < RETENTION_MS
72
91
  })
73
- await writeJsonAtomic(filePath, tasks)
92
+ await writeJsonAtomic(filePath, { schemaVersion: SCHEDULER_SCHEMA_VERSION, tasks })
74
93
  } catch (err) {
75
94
  logger?.warn?.('[dsh-messenger-gateway] scheduler save failed:', err?.message || err)
76
95
  }
@@ -16,8 +16,17 @@ export function setupSettings(ctx, { namespace, Config, resolveConfig, baseConfi
16
16
  }
17
17
  }
18
18
 
19
+ // Bus listeners are registered INSIDE a ctx.effect (#223): when the plugin
20
+ // instance is disposed the unbinds run even if the settings service never
21
+ // mounted, and a repeated apply cannot accumulate stale listeners.
19
22
  const unbinds = []
20
- if (typeof ctx?.on === 'function') {
23
+ const unbindBusListeners = () => {
24
+ for (const unbind of unbinds.splice(0)) {
25
+ try { unbind() } catch (err) { logger?.debug?.(`${namespace}: unbind error:`, err?.message || err) }
26
+ }
27
+ }
28
+ const registerBusListeners = () => {
29
+ if (typeof ctx?.on !== 'function') return
21
30
  const u1 = ctx.on('loader/volatile-update', () => applyLiveConfig())
22
31
  if (typeof u1 === 'function') unbinds.push(u1)
23
32
  const u2 = ctx.on('internal/update', (cfg) => applyLiveConfig(cfg))
@@ -25,11 +34,25 @@ export function setupSettings(ctx, { namespace, Config, resolveConfig, baseConfi
25
34
  const u3 = ctx.on('app-boot/config-reload', () => applyLiveConfig())
26
35
  if (typeof u3 === 'function') unbinds.push(u3)
27
36
  }
37
+ if (typeof ctx?.effect === 'function') {
38
+ ctx.effect(() => {
39
+ registerBusListeners()
40
+ return unbindBusListeners
41
+ }, `${namespace}: bus listeners`)
42
+ } else {
43
+ registerBusListeners()
44
+ }
28
45
 
46
+ let mounted = false
29
47
  const mountSettings = (sctx) => {
48
+ // Idempotent mount (#223): a settings service that re-emits its mount
49
+ // event must not re-register watchers or duplicate subscriptions. A call
50
+ // without a service does not count as a mount.
51
+ if (mounted) return
30
52
  const service = sctx?.settings || (typeof sctx?.get === 'function' ? sctx.get('settings') : null)
31
53
  const effect = typeof sctx?.effect === 'function' ? sctx.effect.bind(sctx) : (typeof ctx.effect === 'function' ? ctx.effect.bind(ctx) : null)
32
54
  if (!service) return
55
+ mounted = true
33
56
 
34
57
  if (typeof service.register === 'function') {
35
58
  settingsApi = service.register(namespace, Config, { base: baseConfig || {} })
@@ -96,10 +119,19 @@ export function setupSettings(ctx, { namespace, Config, resolveConfig, baseConfi
96
119
  return currentConfig
97
120
  }
98
121
 
122
+ let writeChain = Promise.resolve()
99
123
  settingsApi = {
100
124
  get: () => source(),
101
125
  replace: async (next) => persist(next),
102
126
  update: async (patch) => persist({ ...source(), ...patch }),
127
+ // Serialized write mutex (#221): concurrent read-modify-write writers
128
+ // (PUT /config, chat persist hooks) chain through this queue and each
129
+ // re-reads the current config at execution time, so no update is lost.
130
+ writeExclusive: (fn) => {
131
+ const run = writeChain.then(() => fn(settingsApi))
132
+ writeChain = run.then(() => {}, () => {})
133
+ return run
134
+ },
103
135
  watch: (cb) => {
104
136
  if (typeof cb === 'function') watchers.add(cb)
105
137
  const unwatchService = typeof service.watch === 'function' ? service.watch(cb) : null
@@ -111,17 +143,22 @@ export function setupSettings(ctx, { namespace, Config, resolveConfig, baseConfi
111
143
  }
112
144
 
113
145
  const onFn = typeof sctx?.on === 'function' ? sctx.on.bind(sctx) : (typeof ctx?.on === 'function' ? ctx.on.bind(ctx) : null)
146
+ let unbindDocumentUpdated = null
114
147
  if (onFn) {
115
148
  const d1 = onFn('settings/document-updated', (updatedNs) => {
116
149
  if (updatedNs === namespace) applyLiveConfig()
117
150
  })
118
- if (typeof d1 === 'function') unbinds.push(d1)
151
+ if (typeof d1 === 'function') unbindDocumentUpdated = d1
119
152
  }
120
153
 
121
154
  if (effect) {
122
155
  effect(() => () => {
123
- for (const unbind of unbinds) {
124
- try { unbind() } catch (err) { logger?.debug?.(`${namespace}: unbind error:`, err?.message || err) }
156
+ // Bus listeners (loader/volatile-update etc.) belong to the top-level
157
+ // effect above; this dispose only cleans the settings-service side
158
+ // (#223).
159
+ if (unbindDocumentUpdated) {
160
+ try { unbindDocumentUpdated() } catch (err) { logger?.debug?.(`${namespace}: unbind error:`, err?.message || err) }
161
+ unbindDocumentUpdated = null
125
162
  }
126
163
  settingsApi = undefined
127
164
  }, `${namespace}: settings`)
@@ -1,5 +1,5 @@
1
- import { writeFile, rename, mkdir, unlink } from 'node:fs/promises'
2
- import { writeFileSync, renameSync, mkdirSync, unlinkSync } from 'node:fs'
1
+ import { open, rename, mkdir, unlink } from 'node:fs/promises'
2
+ import { renameSync, mkdirSync, unlinkSync, openSync, writeSync, fsyncSync, closeSync, readFileSync, existsSync } from 'node:fs'
3
3
  import { dirname } from 'node:path'
4
4
  import { randomUUID } from 'node:crypto'
5
5
 
@@ -10,7 +10,55 @@ const FILE_MODE = 0o600
10
10
  const DIR_MODE = 0o700
11
11
 
12
12
  /**
13
- * Write JSON atomically via temporary file and rename.
13
+ * A state file could not be parsed and no usable backup existed (#227).
14
+ * The corrupted bytes are never deleted: a preserved copy keeps the path in
15
+ * `corruptBackup` so nothing is lost silently.
16
+ */
17
+ export class StateCorruptError extends Error {
18
+ constructor(filePath, cause) {
19
+ super(`state file ${filePath} is corrupted and no valid backup exists`)
20
+ this.name = 'StateCorruptError'
21
+ this.code = 'STATE_CORRUPT'
22
+ this.filePath = filePath
23
+ this.corruptBackup = null
24
+ this.cause = cause
25
+ }
26
+ }
27
+
28
+ /** The state file was written by a NEWER schema version than this build supports. */
29
+ export class StateVersionError extends Error {
30
+ constructor(filePath, fileVersion, supportedVersion) {
31
+ super(`state file ${filePath} has schema version ${fileVersion}, newer than supported ${supportedVersion}`)
32
+ this.name = 'StateVersionError'
33
+ this.code = 'STATE_VERSION'
34
+ this.filePath = filePath
35
+ }
36
+ }
37
+
38
+ async function fsyncDir(dir) {
39
+ let fh
40
+ try {
41
+ fh = await open(dir, 'r')
42
+ await fh.sync()
43
+ } catch { /* directory fsync is best-effort (some filesystems refuse it) */ }
44
+ finally { try { await fh?.close() } catch { /* ignore */ } }
45
+ }
46
+
47
+ function fsyncDirSync(dir) {
48
+ let fd
49
+ try {
50
+ fd = openSync(dir, 'r')
51
+ fsyncSync(fd)
52
+ } catch { /* best-effort */ }
53
+ finally { try { if (fd !== undefined) closeSync(fd) } catch { /* ignore */ } }
54
+ }
55
+
56
+ /**
57
+ * Write JSON atomically via temporary file and rename (#227):
58
+ * - the temp file is fsynced BEFORE the rename, so a power cut right after
59
+ * the rename cannot leave an empty or partial state file;
60
+ * - the directory is fsynced after the rename so the rename itself survives;
61
+ * - the previous good version is kept as `<path>.bak` for recovery.
14
62
  * Guarantees that readers never observe partially written files.
15
63
  */
16
64
  export async function writeJsonAtomic(filePath, data) {
@@ -18,27 +66,145 @@ export async function writeJsonAtomic(filePath, data) {
18
66
  await mkdir(dir, { recursive: true, mode: DIR_MODE })
19
67
  const tmpPath = `${filePath}.${randomUUID().slice(0, 8)}.tmp`
20
68
  const serialized = JSON.stringify(data, null, 2)
69
+ let fh
21
70
  try {
22
- await writeFile(tmpPath, serialized, { encoding: 'utf8', mode: FILE_MODE })
23
- await rename(tmpPath, filePath)
71
+ fh = await open(tmpPath, 'w', FILE_MODE)
72
+ await fh.writeFile(serialized, { encoding: 'utf8' })
73
+ await fh.sync()
74
+ await fh.close()
75
+ fh = undefined
76
+ // Keep the last good version as a recovery sidecar; rotate, then move
77
+ // the new file into place, restoring the backup if the rename fails.
78
+ let hadPrevious = false
79
+ try {
80
+ await rename(filePath, `${filePath}.bak`)
81
+ hadPrevious = true
82
+ } catch (err) {
83
+ if (err?.code !== 'ENOENT') throw err
84
+ }
85
+ try {
86
+ await rename(tmpPath, filePath)
87
+ } catch (err) {
88
+ if (hadPrevious) await rename(`${filePath}.bak`, filePath).catch(() => { void 0 })
89
+ throw err
90
+ }
91
+ await fsyncDir(dir)
24
92
  } catch (err) {
93
+ try { await fh?.close() } catch { /* ignore */ }
25
94
  await unlink(tmpPath).catch((e) => { void e })
26
95
  throw err
27
96
  }
28
97
  }
29
98
 
30
99
  /**
31
- * Synchronous atomic JSON write via temporary file and rename.
100
+ * Synchronous atomic JSON write: fsync temp file, rotate previous version
101
+ * to `<path>.bak`, rename, fsync directory (#227).
32
102
  */
33
103
  export function writeJsonAtomicSync(filePath, data) {
34
104
  const dir = dirname(filePath)
35
105
  mkdirSync(dir, { recursive: true, mode: DIR_MODE })
36
106
  const tmpPath = `${filePath}.${randomUUID().slice(0, 8)}.tmp`
107
+ let fd
37
108
  try {
38
- writeFileSync(tmpPath, JSON.stringify(data, null, 2), { encoding: 'utf8', mode: FILE_MODE })
39
- renameSync(tmpPath, filePath)
109
+ fd = openSync(tmpPath, 'w', FILE_MODE)
110
+ writeSync(fd, JSON.stringify(data, null, 2), 0, 'utf8')
111
+ fsyncSync(fd)
112
+ } finally {
113
+ try { if (fd !== undefined) closeSync(fd) } catch { /* ignore */ }
114
+ }
115
+ try {
116
+ let hadPrevious = false
117
+ try {
118
+ renameSync(filePath, `${filePath}.bak`)
119
+ hadPrevious = true
120
+ } catch (err) {
121
+ if (err?.code !== 'ENOENT') throw err
122
+ }
123
+ try {
124
+ renameSync(tmpPath, filePath)
125
+ } catch (err) {
126
+ if (hadPrevious) { try { renameSync(`${filePath}.bak`, filePath) } catch { /* ignore */ } }
127
+ throw err
128
+ }
129
+ fsyncDirSync(dir)
40
130
  } catch (err) {
41
131
  try { unlinkSync(tmpPath) } catch { /* ignore */ }
42
132
  throw err
43
133
  }
44
134
  }
135
+
136
+ /**
137
+ * Apply the schema version policy to a parsed state file (#227).
138
+ * Legacy files (no `schemaVersion`) go through `migrate(raw, 0)`.
139
+ * @param {any} parsed parsed JSON payload
140
+ * @param {number} version the schema version this build supports
141
+ * @param {((raw: any, fromVersion: number) => any) | undefined} migrate
142
+ * @param {string} filePath only used for error messages
143
+ */
144
+ function applySchemaVersion(parsed, version, migrate, filePath) {
145
+ const fileVersion = Number(parsed?.schemaVersion)
146
+ if (!Number.isFinite(fileVersion)) {
147
+ // Legacy pre-versioning file: migrate from v0.
148
+ if (typeof migrate !== 'function') return { ...parsed }
149
+ return migrate(parsed, 0)
150
+ }
151
+ if (fileVersion > version) throw new StateVersionError(filePath, fileVersion, version)
152
+ if (fileVersion < version) {
153
+ if (typeof migrate !== 'function') throw new StateVersionError(filePath, fileVersion, version)
154
+ return migrate(parsed, fileVersion)
155
+ }
156
+ return parsed
157
+ }
158
+
159
+ /**
160
+ * Recover from a corrupted state file (#227): the corrupted bytes are moved
161
+ * aside to a timestamped `<path>.corrupt-<ts>` copy (never deleted), then the
162
+ * `<path>.bak` sidecar written by the previous save is tried. If the backup
163
+ * parses, it self-heals the main file and is returned. Otherwise a
164
+ * StateCorruptError is thrown — callers must NOT fall back to empty state
165
+ * silently.
166
+ */
167
+ function recoverCorrupt(filePath, version, migrate, cause) {
168
+ const stamp = new Date().toISOString().replace(/[:.]/g, '-')
169
+ const corruptPath = `${filePath}.corrupt-${stamp}`
170
+ try { renameSync(filePath, corruptPath) } catch { /* best-effort preservation */ }
171
+ const bakPath = `${filePath}.bak`
172
+ if (existsSync(bakPath)) {
173
+ try {
174
+ const bakParsed = JSON.parse(readFileSync(bakPath, 'utf8'))
175
+ if (bakParsed === null || typeof bakParsed !== 'object') throw new Error('backup is not an object')
176
+ const data = applySchemaVersion(bakParsed, version, migrate, filePath)
177
+ try { writeJsonAtomicSync(filePath, data) } catch { /* self-heal is best-effort */ }
178
+ return { data, recovered: true, corruptBackup: corruptPath }
179
+ } catch { /* backup unusable: fall through to the explicit error */ }
180
+ }
181
+ const err = new StateCorruptError(filePath, cause)
182
+ err.corruptBackup = existsSync(corruptPath) ? corruptPath : null
183
+ throw err
184
+ }
185
+
186
+ /**
187
+ * Read a versioned JSON state file synchronously (#227).
188
+ * - missing file: `{ data: null, recovered: false }`
189
+ * - legacy/older schema: migrated through `migrate`
190
+ * - corrupted file: recovered from `.bak` when possible, otherwise
191
+ * StateCorruptError (corrupted bytes preserved next to the file)
192
+ * - newer schema than this build: StateVersionError
193
+ *
194
+ * @param {string} filePath state file path
195
+ * @param {{ version?: number, migrate?: (raw: any, fromVersion: number) => any }} [opts]
196
+ * @returns {{ data: any, recovered: boolean, corruptBackup: string | null }}
197
+ */
198
+ export function readJsonStateSync(filePath, { version = 1, migrate } = {}) {
199
+ if (!filePath || !existsSync(filePath)) return { data: null, recovered: false, corruptBackup: null }
200
+ let parsed
201
+ try {
202
+ parsed = JSON.parse(readFileSync(filePath, 'utf8'))
203
+ } catch (err) {
204
+ return recoverCorrupt(filePath, version, migrate, err)
205
+ }
206
+ if (parsed === null || typeof parsed !== 'object') {
207
+ return recoverCorrupt(filePath, version, migrate, new Error(`unexpected payload type ${typeof parsed}`))
208
+ }
209
+ return { data: applySchemaVersion(parsed, version, migrate, filePath), recovered: false, corruptBackup: null }
210
+ }
File without changes
package/lib/text.js CHANGED
@@ -14,6 +14,56 @@ export function splitText(text, maxLen) {
14
14
  return chunks
15
15
  }
16
16
 
17
+ /**
18
+ * Split raw markdown into chunks whose FORMATTED rendering (measured by
19
+ * `measure`) stays within `budget`, so no HTML tag is ever cut at a chunk
20
+ * boundary (#229). Fence-aware: lines inside ``` fences always stay with
21
+ * their block. A single oversized unit (huge fenceless line) is hard-split.
22
+ *
23
+ * @param {string} text raw markdown
24
+ * @param {number} budget max allowed length of the FORMATTED chunk
25
+ * @param {(s: string) => string} measure renders raw markdown to its
26
+ * Telegram HTML form (used for length measurement)
27
+ * @returns {string[]} raw markdown chunks (format each separately)
28
+ */
29
+ export function splitMarkdownForTelegram(text, budget, measure) {
30
+ const raw = String(text ?? '')
31
+ if (measure(raw).length <= budget) return [raw]
32
+ const chunks = []
33
+ let cur = ''
34
+ let fence = false
35
+
36
+ const flushCur = () => {
37
+ const trimmed = cur.replace(/^\n+/, '').replace(/\n+$/, '')
38
+ if (trimmed) chunks.push(trimmed)
39
+ cur = ''
40
+ }
41
+
42
+ for (const line of raw.split('\n')) {
43
+ if (line.trimStart().startsWith('```')) fence = !fence
44
+ const candidate = cur ? cur + '\n' + line : line
45
+ if (fence || measure(candidate).length <= budget) {
46
+ // Inside a fence we must keep the block intact even over budget; the
47
+ // pathological single-fence-megablock case is hard-split below.
48
+ cur = candidate
49
+ continue
50
+ }
51
+ flushCur()
52
+ cur = line
53
+ if (measure(cur).length > budget) {
54
+ // Single long line without fences: hard-split at word boundaries.
55
+ while (measure(cur).length > budget) {
56
+ let cut = cur.lastIndexOf(' ', budget)
57
+ if (cut < budget / 2) cut = budget
58
+ chunks.push(cur.slice(0, cut).trim())
59
+ cur = cur.slice(cut).trim()
60
+ }
61
+ }
62
+ }
63
+ flushCur()
64
+ return chunks.length > 0 ? chunks : [raw]
65
+ }
66
+
17
67
  export function assistantText(message) {
18
68
  return (message?.content || [])
19
69
  .filter((block) => block.type === 'text')
@@ -1,38 +1,48 @@
1
- import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync, unlinkSync } from "node:fs"
2
- import { dirname } from "node:path"
3
- import { randomUUID } from "node:crypto"
1
+ import { writeJsonAtomicSync, readJsonStateSync, StateCorruptError } from "./storage-atomic.js"
4
2
 
5
- function writeJsonAtomicSync(filePath, data) {
6
- const dir = dirname(filePath)
7
- mkdirSync(dir, { recursive: true, mode: 0o700 })
8
- const tmpPath = `${filePath}.${randomUUID().slice(0, 8)}.tmp`
9
- try {
10
- writeFileSync(tmpPath, JSON.stringify(data, null, 2), { encoding: "utf8", mode: 0o600 })
11
- renameSync(tmpPath, filePath)
12
- } catch (err) {
13
- try { unlinkSync(tmpPath) } catch { /* safe best-effort temp file cleanup */ }
14
- throw err
15
- }
3
+ const VOICE_PREFS_SCHEMA_VERSION = 1
4
+
5
+ // Legacy files store the prefs map at the top level; v1 wraps it so the
6
+ // schema version field never collides with a user id key (#227).
7
+ const migrateVoicePrefs = (raw) => ({
8
+ schemaVersion: VOICE_PREFS_SCHEMA_VERSION,
9
+ prefs: raw && typeof raw === "object" ? raw : {},
10
+ })
11
+
12
+ const logLoadFailure = (logger, kind, err) => {
13
+ const detail = err instanceof StateCorruptError
14
+ ? `state file corrupted and unrecoverable; starting empty; corrupted copy preserved at ${err.corruptBackup || "an unknown path"}`
15
+ : `read error: ${err?.message || err}`
16
+ const message = `[dsh-messenger-gateway] ${kind} ${detail}`
17
+ if (typeof logger?.error === "function") logger.error(message)
18
+ else logger?.warn?.(message)
16
19
  }
17
20
 
18
21
  /** @param {string} filePath @param {any} [opts] */
19
- export function createVoicePrefs(filePath, { logger } = {}) {
22
+ export function createVoicePrefs(filePath, { logger, kind = "voice prefs" } = {}) {
20
23
  /** @type {Record<string, boolean>} */
21
24
  let state = {}
22
- if (filePath && existsSync(filePath)) {
25
+ if (filePath) {
23
26
  try {
24
- const raw = JSON.parse(readFileSync(filePath, "utf8"))
25
- if (raw && typeof raw === "object") state = raw
27
+ const { data, recovered, corruptBackup } = readJsonStateSync(filePath, {
28
+ version: VOICE_PREFS_SCHEMA_VERSION,
29
+ migrate: migrateVoicePrefs,
30
+ })
31
+ if (data) state = data.prefs && typeof data.prefs === "object" ? data.prefs : {}
32
+ if (recovered) {
33
+ logger?.warn?.(`[dsh-messenger-gateway] ${kind} recovered from .bak after corruption; preserved copy: ${corruptBackup}`)
34
+ }
26
35
  } catch (err) {
27
- logger?.warn?.('[dsh-messenger-gateway] voice prefs read error:', err?.message || err)
36
+ if (err instanceof StateCorruptError || err?.name === "StateVersionError") logLoadFailure(logger, kind, err)
37
+ else logger?.warn?.(`[dsh-messenger-gateway] ${kind} read error:`, err?.message || err)
28
38
  }
29
39
  }
30
40
  const persist = () => {
31
41
  if (!filePath) return
32
42
  try {
33
- writeJsonAtomicSync(filePath, state)
43
+ writeJsonAtomicSync(filePath, { schemaVersion: VOICE_PREFS_SCHEMA_VERSION, prefs: state })
34
44
  } catch (err) {
35
- logger?.warn?.('[dsh-messenger-gateway] voice prefs persist error:', err?.message || err)
45
+ logger?.warn?.(`[dsh-messenger-gateway] ${kind} persist error:`, err?.message || err)
36
46
  }
37
47
  }
38
48
  const key = (userId) => String(Number(userId) || userId || "")
package/lib/workspace.js CHANGED
@@ -5,7 +5,7 @@ import { readFileSync } from 'node:fs'
5
5
  import { randomUUID } from 'node:crypto'
6
6
  import os from 'node:os'
7
7
  import path from 'node:path'
8
- import { writeJsonAtomic } from './storage-atomic.js'
8
+ import { writeJsonAtomic, writeJsonAtomicSync, readJsonStateSync, StateCorruptError } from './storage-atomic.js'
9
9
 
10
10
  /**
11
11
  * Validates configured cwd path and returns an error description if invalid.
@@ -148,7 +148,6 @@ export async function registerSessionInWorkspace(ctx, sessionId, cwd, logger) {
148
148
 
149
149
  return false
150
150
  }
151
- import { writeJsonAtomicSync } from "./storage-atomic.js"
152
151
 
153
152
  export function inspectGitWorkspace(dirPath) {
154
153
  try {
@@ -170,27 +169,40 @@ export function inspectGitWorkspace(dirPath) {
170
169
  return { isGit: false, isWorktree: false }
171
170
  }
172
171
 
172
+ const TOPIC_WORKSPACES_SCHEMA_VERSION = 1
173
+
174
+ // Legacy files carried the workspace map bare or under {workspaces}; v1 adds
175
+ // the schema version envelope (#227).
176
+ const migrateTopicWorkspaces = (raw) => ({
177
+ schemaVersion: TOPIC_WORKSPACES_SCHEMA_VERSION,
178
+ workspaces: raw?.workspaces && typeof raw.workspaces === "object" ? raw.workspaces : (raw && typeof raw === "object" ? raw : {}),
179
+ })
180
+
173
181
  /** @param {string} filePath @param {any} [opts] */
174
182
  export function createTopicWorkspaceStore(filePath, { logger } = {}) {
175
183
  let cache = { workspaces: {} }
176
184
  try {
177
- if (existsSync(filePath)) {
178
- const raw = JSON.parse(readFileSync(filePath, "utf8"))
179
- if (raw && typeof raw === "object" && raw.workspaces) {
180
- cache = raw
181
- } else if (raw && typeof raw === "object") {
182
- cache = { workspaces: raw }
183
- }
185
+ const { data, recovered, corruptBackup } = readJsonStateSync(filePath, {
186
+ version: TOPIC_WORKSPACES_SCHEMA_VERSION,
187
+ migrate: migrateTopicWorkspaces,
188
+ })
189
+ if (data) cache = { workspaces: data.workspaces && typeof data.workspaces === "object" ? data.workspaces : {} }
190
+ if (recovered) {
191
+ logger?.warn?.(`[dsh-messenger-gateway] topic-workspaces recovered from .bak after corruption; preserved copy: ${corruptBackup}`)
184
192
  }
185
193
  } catch (err) {
186
- if (err?.code !== "ENOENT") {
194
+ if (err instanceof StateCorruptError || err?.name === "StateVersionError") {
195
+ const message = `[dsh-messenger-gateway] topic-workspaces corrupted; starting empty; corrupted copy preserved at ${err.corruptBackup || filePath}`
196
+ if (typeof logger?.error === "function") logger.error(message)
197
+ else logger?.warn?.(message)
198
+ } else if (err?.code !== "ENOENT") {
187
199
  logger?.warn?.(`[dsh-messenger-gateway] topic-workspaces load error: ${err?.message || err}`)
188
200
  }
189
201
  }
190
202
 
191
203
  function save() {
192
204
  try {
193
- writeJsonAtomicSync(filePath, cache)
205
+ writeJsonAtomicSync(filePath, { schemaVersion: TOPIC_WORKSPACES_SCHEMA_VERSION, ...cache })
194
206
  } catch (err) {
195
207
  logger?.warn?.(`[dsh-messenger-gateway] topic-workspaces save error: ${err?.message || err}`)
196
208
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@goodandready/dsh-messenger-gateway",
3
- "version": "0.4.43",
3
+ "version": "0.4.45",
4
4
  "description": "Telegram messenger bridge for DeepSeek Harness: sessions, steer, homes, inline asks, notify bridge, and optional TTS voice notes.",
5
5
  "license": "MIT",
6
6
  "type": "module",