@xmanrui/dsh-im 0.12.0 → 0.14.0

package/src/channels/office/office-runtime.mjs

@@ -0,0 +1,171 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+
+import { OfficeTransport } from './office-transport.mjs';
+import { OFFICE_PROTOCOL_VERSION } from './protocol.mjs';
+import { OfficeJobExecutor } from './office-job-executor.mjs';
+
+const RETRY_DELAYS = Object.freeze([1_000, 3_000, 10_000, 30_000]);
+
+function safeConnectionError(error) {
+  const code = typeof error?.code === 'string' ? error.code : 'office-connection-failed';
+  const messages = {
+    'invalid-device-token': 'AI Office 拒绝了 Device Token。',
+    'office-hook-unavailable': 'AI Office Connector Hook 尚未就绪。',
+    'office-protocol-mismatch': 'AI Office Connector 协议版本不兼容。',
+    'office-transport-failed': '本机暂时无法访问 AI Office。',
+  };
+  return { code, message: messages[code] ?? 'AI Office 连接已中断。' };
+}
+
+export class OfficeRuntime {
+  #config;
+  #token;
+  #logger;
+  #transport;
+  #sleep;
+  #controller = null;
+  #task = null;
+  #status;
+  #jobs;
+
+  constructor({
+    config,
+    token,
+    logger = console,
+    transport,
+    createHarness,
+    jobExecutor,
+    sleepImpl = sleep,
+  }) {
+    this.#config = config;
+    this.#token = token;
+    this.#logger = logger;
+    this.#sleep = sleepImpl;
+    this.#transport = transport ?? new OfficeTransport({
+      baseUrl: config.baseUrl, deviceId: config.deviceId, token,
+    });
+    this.#status = {
+      state: 'idle', connected: false, startedAt: null, lastHeartbeatAt: null,
+      lastEventAt: null, lastEventId: null, lastEventType: null, reconnects: 0,
+      jobsOffered: 0, error: null,
+    };
+    this.#jobs = jobExecutor ?? (createHarness ? new OfficeJobExecutor({
+      config,
+      transport: this.#transport,
+      createHarness,
+      logger,
+    }) : null);
+  }
+
+  get status() {
+    return structuredClone({
+      ...this.#status,
+      ...(this.#jobs ? { jobs: this.#jobs.status } : {}),
+    });
+  }
+
+  capabilities() {
+    return {
+      protocolVersion: OFFICE_PROTOCOL_VERSION,
+      deviceId: this.#config.deviceId,
+      workspaces: Object.keys(this.#config.workspaces),
+      instructionPresets: Object.keys(this.#config.instructionPresets),
+      maxConcurrency: this.#config.maxConcurrency,
+    };
+  }
+
+  async testConnection(signal) {
+    await this.#transport.heartbeat({ ...this.capabilities(), probe: true }, { signal });
+    return { ok: true };
+  }
+
+  start() {
+    if (this.#task) return this.status;
+    this.#controller = new AbortController();
+    this.#status.startedAt = new Date().toISOString();
+    this.#status.state = 'connecting';
+    this.#task = this.#run(this.#controller.signal).finally(() => { this.#task = null; });
+    this.#task.catch((error) => {
+      if (this.#controller?.signal.aborted) return;
+      this.#logger.error?.('[dsh-im:office] connector stopped:', error);
+    });
+    return this.status;
+  }
+
+  async #run(signal) {
+    let attempt = 0;
+    while (!signal.aborted) {
+      const attemptController = new AbortController();
+      const attemptSignal = AbortSignal.any([signal, attemptController.signal]);
+      try {
+        const heartbeat = await this.#transport.heartbeat(this.capabilities(), { signal: attemptSignal });
+        this.#offerJobs(heartbeat?.jobs);
+        this.#status.lastHeartbeatAt = new Date().toISOString();
+        let streamOpened = false;
+        const heartbeatTask = this.#heartbeatLoop(attemptSignal, () => {
+          if (streamOpened && !attemptSignal.aborted) attempt = 0;
+        });
+        const stream = this.#transport.stream({
+          signal: attemptSignal,
+          lastEventId: this.#status.lastEventId,
+          onOpen: () => {
+            this.#status.connected = true;
+            this.#status.state = 'connected';
+            this.#status.error = null;
+            streamOpened = true;
+          },
+          onEvent: async (event) => {
+            this.#status.lastEventAt = new Date().toISOString();
+            this.#status.lastEventId = event.id ?? this.#status.lastEventId;
+            this.#status.lastEventType = event.type;
+            if (event.type === 'job.available') this.#status.jobsOffered += 1;
+            this.#jobs?.handleEvent(event);
+          },
+        });
+        await Promise.race([stream, heartbeatTask]);
+      } catch (error) {
+        if (signal.aborted) break;
+        attemptController.abort();
+        this.#status.connected = false;
+        this.#status.state = 'reconnecting';
+        this.#status.error = safeConnectionError(error);
+        this.#status.reconnects += 1;
+        const delay = RETRY_DELAYS[Math.min(attempt, RETRY_DELAYS.length - 1)];
+        attempt += 1;
+        try { await this.#sleep(delay, undefined, { signal }); } catch { break; }
+      } finally {
+        attemptController.abort();
+      }
+    }
+    this.#status.connected = false;
+    this.#status.state = 'idle';
+  }
+
+  async #heartbeatLoop(signal, onSuccess) {
+    while (!signal.aborted) {
+      await this.#sleep(this.#config.heartbeatSeconds * 1_000, undefined, { signal });
+      const heartbeat = await this.#transport.heartbeat(this.capabilities(), { signal });
+      this.#offerJobs(heartbeat?.jobs);
+      this.#status.lastHeartbeatAt = new Date().toISOString();
+      onSuccess?.();
+    }
+  }
+
+  #offerJobs(jobs) {
+    if (!Array.isArray(jobs)) return;
+    for (const job of jobs) {
+      if (typeof job?.id === 'string' && this.#jobs?.offer(job.id)) this.#status.jobsOffered += 1;
+    }
+  }
+
+  async stop() {
+    const task = this.#task;
+    this.#controller?.abort();
+    this.#controller = null;
+    if (task) await task.catch(() => undefined);
+    await this.#jobs?.close();
+    this.#status.connected = false;
+    this.#status.state = 'idle';
+    return this.status;
+  }
+}

package/src/channels/office/office-transport.mjs

@@ -0,0 +1,170 @@
+import { OFFICE_HOOK_PATHS, OFFICE_PROTOCOL_VERSION, officeHookUrls } from './protocol.mjs';
+
+function safeTransportError(operation, response) {
+  const error = new Error(`AI Office ${operation} failed: HTTP ${response.status}`);
+  error.code = response.status === 401 ? 'invalid-device-token'
+    : response.status === 404 ? 'office-hook-unavailable'
+      : response.status === 409 ? 'office-job-conflict' : 'office-transport-failed';
+  return error;
+}
+
+function transportFailure(message, code = 'office-transport-failed', cause) {
+  const error = new Error(message, cause === undefined ? undefined : { cause });
+  error.code = code;
+  return error;
+}
+
+function isAbort(error, signal) {
+  return signal?.aborted || error?.name === 'AbortError';
+}
+
+function parseFrame(frame) {
+  let type = 'message';
+  let id;
+  const data = [];
+  for (const line of frame.split(/\r?\n/)) {
+    if (line.startsWith('event:')) type = line.slice(6).trim() || 'message';
+    else if (line.startsWith('id:')) id = line.slice(3).trim() || undefined;
+    else if (line.startsWith('data:')) data.push(line.slice(5).trimStart());
+  }
+  if (data.length === 0) return null;
+  let value;
+  try { value = JSON.parse(data.join('\n')); } catch { throw new Error('AI Office SSE returned invalid JSON'); }
+  return { id, type: typeof value?.type === 'string' ? value.type : type, data: value };
+}
+
+export class OfficeTransport {
+  #baseUrl;
+  #deviceId;
+  #token;
+  #fetch;
+
+  constructor({ baseUrl, deviceId, token, fetchImpl = fetch }) {
+    this.#baseUrl = baseUrl;
+    this.#deviceId = deviceId;
+    this.#token = token;
+    this.#fetch = fetchImpl;
+  }
+
+  hooks() { return officeHookUrls(this.#baseUrl); }
+
+  #headers(extra = {}) {
+    return {
+      authorization: `Bearer ${this.#token}`,
+      'x-harness-device-id': this.#deviceId,
+      ...extra,
+    };
+  }
+
+  async heartbeat(payload, { signal } = {}) {
+    let response;
+    try {
+      response = await this.#fetch(new URL(OFFICE_HOOK_PATHS.heartbeat, this.#baseUrl), {
+        method: 'POST',
+        headers: this.#headers({ accept: 'application/json', 'content-type': 'application/json' }),
+        body: JSON.stringify(payload),
+        signal,
+        redirect: 'error',
+      });
+    } catch (error) {
+      if (isAbort(error, signal)) throw error;
+      throw transportFailure('AI Office heartbeat request could not be completed', undefined, error);
+    }
+    if (!response.ok) throw safeTransportError('heartbeat', response);
+    let value;
+    try { value = await response.json(); }
+    catch (error) { throw transportFailure('AI Office heartbeat returned invalid JSON', 'office-protocol-mismatch', error); }
+    if (!value || typeof value !== 'object' || value.ok !== true
+      || value.protocolVersion !== OFFICE_PROTOCOL_VERSION) {
+      throw transportFailure('AI Office heartbeat protocol does not match', 'office-protocol-mismatch');
+    }
+    return value;
+  }
+
+  async #jobRequest(path, { method = 'POST', body, leaseToken, signal } = {}) {
+    const headers = this.#headers({ accept: 'application/json' });
+    if (body !== undefined) headers['content-type'] = 'application/json';
+    if (leaseToken) headers['x-harness-lease-token'] = leaseToken;
+    let response;
+    try {
+      response = await this.#fetch(new URL(path, this.#baseUrl), {
+        method,
+        headers,
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        signal,
+        redirect: 'error',
+        cache: 'no-store',
+      });
+    } catch (error) {
+      if (isAbort(error, signal)) throw error;
+      throw transportFailure('AI Office Job request could not be completed', undefined, error);
+    }
+    if (!response.ok) throw safeTransportError('Job request', response);
+    try { return await response.json(); }
+    catch (error) { throw transportFailure('AI Office Job returned invalid JSON', 'office-protocol-mismatch', error); }
+  }
+
+  async getJob(jobId, options = {}) {
+    return this.#jobRequest(OFFICE_HOOK_PATHS.job.replace(':id', jobId), { ...options, method: 'GET' });
+  }
+
+  async acceptJob(jobId, options = {}) {
+    return this.#jobRequest(OFFICE_HOOK_PATHS.accept.replace(':id', jobId), options);
+  }
+
+  async renewJob(jobId, leaseToken, options = {}) {
+    return this.#jobRequest(OFFICE_HOOK_PATHS.renew.replace(':id', jobId), { ...options, leaseToken });
+  }
+
+  async progressJob(jobId, leaseToken, body, options = {}) {
+    return this.#jobRequest(OFFICE_HOOK_PATHS.progress.replace(':id', jobId), { ...options, leaseToken, body });
+  }
+
+  async requestApproval(jobId, leaseToken, body, options = {}) {
+    return this.#jobRequest(OFFICE_HOOK_PATHS.approval.replace(':id', jobId), { ...options, leaseToken, body });
+  }
+
+  async completeJob(jobId, leaseToken, body, options = {}) {
+    return this.#jobRequest(OFFICE_HOOK_PATHS.result.replace(':id', jobId), { ...options, leaseToken, body });
+  }
+
+  async failJob(jobId, leaseToken, body, options = {}) {
+    return this.#jobRequest(OFFICE_HOOK_PATHS.fail.replace(':id', jobId), { ...options, leaseToken, body });
+  }
+
+  async stream({ signal, lastEventId, onOpen, onEvent }) {
+    const headers = this.#headers({ accept: 'text/event-stream' });
+    if (lastEventId) headers['last-event-id'] = lastEventId;
+    let response;
+    try {
+      response = await this.#fetch(new URL(OFFICE_HOOK_PATHS.stream, this.#baseUrl), {
+        method: 'GET', headers, signal, redirect: 'error', cache: 'no-store',
+      });
+    } catch (error) {
+      if (isAbort(error, signal)) throw error;
+      throw transportFailure('AI Office SSE request could not be completed', undefined, error);
+    }
+    if (!response.ok) throw safeTransportError('stream', response);
+    if (!response.headers.get('content-type')?.toLowerCase().includes('text/event-stream')) {
+      throw new Error('AI Office stream did not return text/event-stream');
+    }
+    if (!response.body) throw new Error('AI Office stream returned no body');
+    onOpen?.();
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buffer = `${buffer}${decoder.decode(value, { stream: true })}`.replaceAll('\r\n', '\n');
+      let boundary;
+      while ((boundary = buffer.indexOf('\n\n')) !== -1) {
+        const raw = buffer.slice(0, boundary);
+        buffer = buffer.slice(boundary + 2);
+        const event = parseFrame(raw);
+        if (event) await onEvent?.(event);
+      }
+    }
+    throw new Error('AI Office SSE stream ended');
+  }
+}

package/src/channels/office/protocol.mjs

@@ -0,0 +1,43 @@
+export const OFFICE_PROTOCOL_VERSION = 'office-harness.v1';
+export const OFFICE_RPC_CHANNEL = '/office';
+
+export const OFFICE_RPC_ENDPOINTS = Object.freeze({
+  status: 'connection.status',
+  configure: 'connector.configure',
+  reconnect: 'connector.reconnect',
+  test: 'connector.test',
+  remove: 'connector.remove',
+});
+
+export const OFFICE_HOOK_PATHS = Object.freeze({
+  stream: '/api/harness/connector/stream',
+  heartbeat: '/api/harness/connector/heartbeat',
+  job: '/api/harness/connector/jobs/:id',
+  accept: '/api/harness/connector/jobs/:id/accept',
+  renew: '/api/harness/connector/jobs/:id/renew',
+  progress: '/api/harness/connector/jobs/:id/progress',
+  approval: '/api/harness/connector/jobs/:id/approval',
+  result: '/api/harness/connector/jobs/:id/result',
+  fail: '/api/harness/connector/jobs/:id/fail',
+});
+
+export function normalizeOfficeBaseUrl(value) {
+  const url = new URL(typeof value === 'string' ? value.trim() : '');
+  const localHttp = url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+  if (url.protocol !== 'https:' && !localHttp) {
+    throw new TypeError('AI Office URL must use HTTPS (HTTP is allowed only for loopback testing)');
+  }
+  if (url.username || url.password || url.search || url.hash) {
+    throw new TypeError('AI Office URL must be a bare origin');
+  }
+  url.pathname = '/';
+  return url;
+}
+
+export function officeHookUrls(baseUrl) {
+  const origin = normalizeOfficeBaseUrl(baseUrl);
+  return Object.fromEntries(Object.entries(OFFICE_HOOK_PATHS).map(([name, path]) => [
+    name,
+    new URL(path, origin).toString(),
+  ]));
+}

package/src/channels/qq/qq-bridge.mjs

@@ -46,8 +46,9 @@ const HELP_TEXT = [
   '/workspacelist  列出工作区绝对路径',
   '/sessionlist [工作区序号或绝对路径]  列出会话 ID 和标题',
   '/session Session ID 或当前工作区序号  将当前聊天绑定到指定会话',
-  '/models  列出所有可用模型',
-  '/model [模型ID]  查看或切换当前会话模型',
+  '/models  按序号列出所有可用模型',
+  '/model [序号或完整模型ID]  查看或切换当前会话模型',
+  '示例：先发 /models，再发 /model 2',
   '/stop  停止当前任务',
   '/steer 补充指令  纠偏当前任务',
   '/status  检查连接状态',

package/src/channels/shared/model-command.mjs

@@ -4,7 +4,7 @@ import { withSessionBindingLock } from './session-binding-lock.mjs';
 
 const MODEL_COMMAND = /^\/model(?=$|\s)/i;
 const MODELS_COMMAND = /^\/models(?=$|\s)/i;
-const MODEL_USAGE = '用法：/model <provider>/<model>';
+const MODEL_USAGE = '用法：/model <序号> 或 /model <provider>/<model>';
 const MODELS_USAGE = '用法：/models（不带参数）';
 const SESSION_BINDING_CHANGED = 'session-binding-changed';
 const UNSAFE_DISPLAY_TEXT_GLOBAL = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]+/gu;
@@ -88,17 +88,46 @@ function matchingModel(catalog, requested) {
   return null;
 }
 
+function modelAt(catalog, requestedIndex) {
+  let index = 0;
+  for (const group of catalog.groups) {
+    for (const model of group.models) {
+      index += 1;
+      if (index === requestedIndex) {
+        return { provider: group.id, model: model.id };
+      }
+    }
+  }
+  return null;
+}
+
+function modelNumberRequest(requested) {
+  if (!/^\d+$/u.test(requested)) return null;
+  const index = Number(requested);
+  return { index: Number.isSafeInteger(index) && index > 0 ? index : null };
+}
+
+function invalidModelNumberMessage(requested) {
+  return [
+    `模型序号无效：${safeDisplayText(requested)}`,
+    '',
+    '请发送 /models 查看并输入有效的正整数序号。',
+  ].join('\n');
+}
+
 function formatCatalog(catalog) {
   const currentId = catalog.current
     ? modelId(catalog.current.provider, catalog.current.model)
     : null;
   const lines = ['可用模型：'];
+  let index = 0;
   if (catalog.groups.length === 0) lines.push('', '当前没有可用模型。');
   for (const group of catalog.groups) {
     lines.push('', safeDisplayText(group.name) || safeDisplayText(group.id));
     for (const model of group.models) {
+      index += 1;
       const id = modelId(group.id, model.id);
-      lines.push(`- ${safeDisplayText(id)}${id === currentId ? '（当前）' : ''}`);
+      lines.push(`${index}. ${safeDisplayText(id)}${id === currentId ? '（当前）' : ''}`);
     }
   }
   if (catalog.failures.length > 0) {
@@ -107,6 +136,7 @@ function formatCatalog(catalog) {
       lines.push(`- ${safeDisplayText(failure.name) || safeDisplayText(failure.id)}`);
     }
   }
+  if (index > 0) lines.push('', '切换模型：/model <序号>');
   return lines.join('\n');
 }
 
@@ -116,7 +146,7 @@ function currentModelMessage(current) {
     modelId(current.provider, current.model),
     '',
     '查看全部模型：/models',
-    '切换模型：/model <provider>/<model>',
+    '切换模型：/model <序号>',
   ].join('\n');
 }
 
@@ -125,7 +155,7 @@ function noSessionMessage() {
     '当前聊天还没有会话。',
     '',
     '查看模型：/models',
-    '选择模型：/model <provider>/<model>',
+    '选择模型：/model <序号>',
   ].join('\n');
 }
 
@@ -243,7 +273,12 @@ export async function runModelCommand(text, harness, state, key, options = {}) {
       return commandResult(modelErrorMessage(error, 'select'));
     }
   }
-  if (!requested.includes('/') || requested.startsWith('/') || requested.endsWith('/')) {
+  const numberRequest = modelNumberRequest(requested);
+  if (numberRequest?.index === null) {
+    return commandResult(invalidModelNumberMessage(requested));
+  }
+  if (!numberRequest
+    && (!requested.includes('/') || requested.startsWith('/') || requested.endsWith('/'))) {
     return commandResult(MODEL_USAGE);
   }
   if (options.pendingInteraction) {
@@ -264,8 +299,11 @@ export async function runModelCommand(text, harness, state, key, options = {}) {
       const catalog = bound
         ? await sessionCatalog(bound.session, requestOptions)
         : await listCatalog(harness, requestOptions);
-      const selection = matchingModel(catalog, requested);
+      const selection = numberRequest
+        ? modelAt(catalog, numberRequest.index)
+        : matchingModel(catalog, requested);
       if (!selection) {
+        if (numberRequest) return commandResult(invalidModelNumberMessage(requested));
         return commandResult([
           `没有找到模型：${safeDisplayText(requested)}`,
           '',

package/src/channels/shared/text-harness-bridge.mjs

@@ -316,8 +316,9 @@ export class TextHarnessBridge {
           '/workspacelist  列出工作区绝对路径',
           '/sessionlist [工作区序号或绝对路径]  列出会话 ID 和标题',
           '/session Session ID 或当前工作区序号  将当前聊天绑定到指定会话',
-          '/models  列出所有可用模型',
-          '/model [模型ID]  查看或切换当前会话模型',
+          '/models  按序号列出所有可用模型',
+          '/model [序号或完整模型ID]  查看或切换当前会话模型',
+          '示例：先发 /models，再发 /model 2',
           '/stop  停止当前任务',
           '/steer 补充指令  纠偏当前任务',
           '/status  检查连接状态',

package/src/channels/shared/token-bot-controller.mjs

@@ -163,6 +163,34 @@ export class TokenBotController {
     return this.status();
   }
 
+  async updateBotConfig(botId, update) {
+    if (this.#closed) throw new Error(`${this.#descriptor.label} controller is closed`);
+    if (typeof update !== 'function') throw new TypeError('Bot config update must be a function');
+    await this.#withBotTransition(botId, async () => {
+      if (this.#closed) throw new Error(`${this.#descriptor.label} controller is closed`);
+      const config = this.#configStore.get(botId);
+      if (!config) throw new Error(`Unknown ${this.#descriptor.label} bot`);
+      const token = await this.#resolveToken(config.tokenRef);
+      if (!token) throw new Error(`${this.#descriptor.label} bot token is missing`);
+      if (this.#closed) throw new Error(`${this.#descriptor.label} controller is closed`);
+      const nextConfig = update(config);
+      const savedConfig = await this.#configStore.save(nextConfig);
+      try {
+        await this.#startRuntime(savedConfig, token);
+        this.#errors.delete(botId);
+      } catch (error) {
+        this.#errors.set(botId, safeError(
+          'connection-failed',
+          `${this.#descriptor.label}连接仍未就绪，请稍后重试。`,
+        ));
+        throw error;
+      } finally {
+        this.#touch();
+      }
+    });
+    return this.status();
+  }
+
   async sendConnectionTest(botId) {
     const config = this.#configStore.get(botId);
     if (!config) throw new Error(`Unknown ${this.#descriptor.label} bot`);

package/src/channels/shared/token-config-store.mjs

@@ -33,16 +33,26 @@ export class TokenBotConfigStore {
   #channel;
   #botPrefix;
   #tokenRefPrefix;
+  #normalizeBotExtension;
   #botIdPattern;
   #tokenRefPattern;
   #value = EMPTY_DOCUMENT;
   #writeQueue = Promise.resolve();
 
-  constructor(path, { channel, botPrefix, tokenRefPrefix }) {
+  constructor(path, {
+    channel,
+    botPrefix,
+    tokenRefPrefix,
+    normalizeBotExtension = () => ({}),
+  }) {
+    if (typeof normalizeBotExtension !== 'function') {
+      throw new TypeError('normalizeBotExtension must be a function');
+    }
     this.#path = path;
     this.#channel = channel;
     this.#botPrefix = botPrefix;
     this.#tokenRefPrefix = tokenRefPrefix;
+    this.#normalizeBotExtension = normalizeBotExtension;
     this.#botIdPattern = new RegExp(`^${escapePattern(botPrefix)}_[a-f0-9]{24}$`);
     this.#tokenRefPattern = new RegExp(`^${escapePattern(tokenRefPrefix)}_[A-F0-9]{24}$`);
   }
@@ -127,6 +137,8 @@ export class TokenBotConfigStore {
       tokenRefPrefix: this.#tokenRefPrefix,
     });
     if (derived.botId !== botId || derived.tokenRef !== tokenRef) return null;
+    const extension = this.#normalizeBotExtension(value);
+    if (!extension || typeof extension !== 'object' || Array.isArray(extension)) return null;
     return Object.freeze({
       botId,
       platformId,
@@ -135,6 +147,7 @@ export class TokenBotConfigStore {
       username: cleanString(value.username),
       createdAt: cleanString(value.createdAt) ?? new Date().toISOString(),
       connectedAt: cleanString(value.connectedAt),
+      ...extension,
     });
   }
 

package/src/channels/telegram/config-store.mjs

@@ -9,6 +9,58 @@ const IDENTITY_OPTIONS = Object.freeze({
   tokenRefPrefix: 'DSH_TELEGRAM_BOT_TOKEN',
 });
 
+export const TELEGRAM_ACCESS_MODES = Object.freeze({
+  compatible: 'compatible',
+  privateAllowlist: 'private-allowlist',
+});
+
+const TELEGRAM_USER_ID = /^[1-9]\d{0,15}$/;
+
+export function normalizeTelegramAllowedUsers(value) {
+  if (value === undefined) return Object.freeze([]);
+  if (!Array.isArray(value)) {
+    throw new TypeError('allowedUsers must be an array of numeric Telegram User IDs');
+  }
+  const normalized = value.map((entry) => {
+    const userId = typeof entry === 'number' && Number.isSafeInteger(entry)
+      ? String(entry) : typeof entry === 'string' ? entry.trim() : '';
+    if (!TELEGRAM_USER_ID.test(userId)) {
+      throw new TypeError('allowedUsers contains an invalid Telegram User ID');
+    }
+    return userId;
+  });
+  return Object.freeze([...new Set(normalized)]);
+}
+
+export function normalizeTelegramAccessPolicy(value = {}) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError('Telegram access policy must be an object');
+  }
+  const accessMode = value.accessMode ?? TELEGRAM_ACCESS_MODES.compatible;
+  if (!Object.values(TELEGRAM_ACCESS_MODES).includes(accessMode)) {
+    throw new TypeError('Telegram accessMode must be compatible or private-allowlist');
+  }
+  return Object.freeze({
+    accessMode,
+    allowedUsers: normalizeTelegramAllowedUsers(value.allowedUsers),
+  });
+}
+
+function normalizeTelegramBotExtension(value) {
+  const hasAccessMode = Object.hasOwn(value, 'accessMode');
+  const hasAllowedUsers = Object.hasOwn(value, 'allowedUsers');
+  if (!hasAccessMode && !hasAllowedUsers) return {};
+  try {
+    const policy = normalizeTelegramAccessPolicy(value);
+    return {
+      ...(hasAccessMode ? { accessMode: policy.accessMode } : {}),
+      ...(hasAllowedUsers || hasAccessMode ? { allowedUsers: policy.allowedUsers } : {}),
+    };
+  } catch {
+    return null;
+  }
+}
+
 export function deriveTelegramBotIdentity(platformId) {
   return deriveTokenBotIdentity(platformId, IDENTITY_OPTIONS);
 }
@@ -19,6 +71,15 @@ export function maskTelegramBotId(platformId) {
 
 export class TelegramConfigStore extends TokenBotConfigStore {
   constructor(path) {
-    super(path, { channel: 'Telegram', ...IDENTITY_OPTIONS });
+    super(path, {
+      channel: 'Telegram',
+      ...IDENTITY_OPTIONS,
+      normalizeBotExtension: normalizeTelegramBotExtension,
+    });
+  }
+
+  async save(value) {
+    const previous = value?.platformId ? this.getByPlatformId(String(value.platformId)) : null;
+    return super.save({ ...previous, ...value });
   }
 }