@xmanrui/dsh-im 0.1.0

package/plugin-src/host/channels/qq/production.mjs

@@ -0,0 +1,109 @@
+import { unlink } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+import { QqConfigStore } from '../../../../src/channels/qq/config-store.mjs';
+import { QqHarnessClient } from '../../../../src/channels/qq/harness-client.mjs';
+import { QqController } from '../../../../src/channels/qq/qq-controller.mjs';
+import { QqRuntime } from '../../../../src/channels/qq/qq-runtime.mjs';
+import { QqQrAuth } from '../../../../src/channels/qq/qr-auth.mjs';
+import { QqStateStore } from '../../../../src/channels/qq/state-store.mjs';
+import { createConnectionSupervisor } from './connection-supervisor.mjs';
+
+function harnessOrigin(webServer, configured) {
+  if (configured !== undefined) return new URL(configured);
+  const port = webServer?.port;
+  if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+    throw new Error('dsh-im QQ requires an initialized DSH webServer port');
+  }
+  return new URL(`http://127.0.0.1:${port}`);
+}
+
+function pluginPaths(config) {
+  const dshHome = resolve(config.dshHome ?? process.env.DSH_HOME ?? join(homedir(), '.dsh'));
+  const root = resolve(config.dataDir ?? join(dshHome, 'integrations', 'dsh-qq'));
+  return {
+    config: resolve(config.configPath ?? join(root, 'config.json')),
+    bots: resolve(config.botsDir ?? join(root, 'bots')),
+  };
+}
+
+export async function createProductionController(ctx, config = {}, internals = {}) {
+  if (!ctx?.credentials) throw new TypeError('dsh-im QQ requires ctx.credentials');
+  if (!ctx?.webServer) throw new TypeError('dsh-im QQ requires ctx.webServer');
+
+  const ConfigStore = internals.ConfigStore ?? QqConfigStore;
+  const StateStore = internals.StateStore ?? QqStateStore;
+  const Harness = internals.HarnessClient ?? QqHarnessClient;
+  const Controller = internals.Controller ?? QqController;
+  const Runtime = internals.Runtime ?? QqRuntime;
+  const QrAuth = internals.QrAuth ?? QqQrAuth;
+  const createSupervisor = internals.createConnectionSupervisor ?? createConnectionSupervisor;
+  const logger = typeof ctx.logger === 'function' ? ctx.logger('dsh-im:qq') : (ctx.logger ?? console);
+  const paths = pluginPaths(config);
+  const configStore = await new ConfigStore(paths.config).load();
+  const qrAuth = internals.qrAuth ?? new QrAuth({ source: config.qrSource ?? 'deepseek-harness' });
+  const stateStores = new Map();
+  const statePath = (botId) => resolve(paths.bots, botId, 'state.json');
+  const stateFor = async (botId) => {
+    let state = stateStores.get(botId);
+    if (!state) {
+      state = await new StateStore(statePath(botId)).load();
+      stateStores.set(botId, state);
+    }
+    return state;
+  };
+  const harness = new Harness({
+    baseUrl: harnessOrigin(ctx.webServer, config.harnessBaseUrl),
+    workspace: resolve(config.workspace ?? process.cwd()),
+    agentPreset: config.agentPreset ?? 'standard',
+    autostart: false,
+    dshBin: config.dshBin ?? 'dsh',
+  });
+  const controller = new Controller({
+    qrAuth,
+    credentials: ctx.credentials,
+    configStore,
+    logger,
+    createRuntime: async ({ botId, config: botConfig, appSecret }) => new Runtime({
+      config: botConfig,
+      appSecret,
+      harness,
+      state: await stateFor(botId),
+      replyTimeoutMs: config.replyTimeoutMs ?? 600_000,
+      connectTimeoutMs: config.connectTimeoutMs ?? 20_000,
+      logger: {
+        error: (...args) => logger.error?.(`[${botId}]`, ...args),
+        warn: (...args) => logger.warn?.(`[${botId}]`, ...args),
+        info: (...args) => logger.info?.(`[${botId}]`, ...args),
+        debug: (...args) => logger.debug?.(`[${botId}]`, ...args),
+      },
+    }),
+    deleteState: async ({ botId }) => {
+      const state = stateStores.get(botId);
+      stateStores.delete(botId);
+      if (state && typeof state.remove === 'function') return state.remove();
+      try {
+        await unlink(statePath(botId));
+      } catch (error) {
+        if (error?.code !== 'ENOENT') throw error;
+      }
+    },
+  });
+  const supervisor = createSupervisor({
+    controller,
+    harness,
+    logger,
+    retryDelaysMs: config.retryDelaysMs,
+    healthyIntervalMs: config.healthyIntervalMs,
+  }).start();
+  return {
+    controller,
+    ready: supervisor.ready,
+    async close() {
+      await supervisor.close();
+      await controller.close();
+      harness.stopManagedProcess();
+    },
+  };
+}

package/plugin-src/host/channels/qq/rpc.mjs

@@ -0,0 +1,146 @@
+import QRCode from 'qrcode';
+import { resolveRpcAuthority } from '../../rpc-authority.mjs';
+
+export const QQ_RPC_CHANNEL = '/qq';
+export const QQ_ENDPOINTS = Object.freeze({
+  status: 'connection.status',
+  beginProvisioning: 'provision.begin',
+  pollProvisioning: 'provision.poll',
+  cancelProvisioning: 'provision.cancel',
+  bindCredentials: 'bot.bind-credentials',
+  reconnectBot: 'bot.reconnect',
+  deleteBot: 'bot.delete',
+});
+export const QQ_RPC_ENDPOINTS = Object.freeze(Object.values(QQ_ENDPOINTS));
+
+const FORBIDDEN_PUBLIC_KEYS = new Set([
+  'appSecret', 'app_secret', 'secretRef', 'ownerUserOpenid', 'userOpenid', 'verificationUrl',
+]);
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function exactKeys(value, allowed) {
+  return isRecord(value) && Object.keys(value).every((key) => allowed.includes(key));
+}
+
+function validId(value) {
+  return typeof value === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(value);
+}
+
+function validCredential(value, maxLength) {
+  return typeof value === 'string' && value.trim().length > 0 && value.length <= maxLength;
+}
+
+function payloadFailure(endpoint, payload) {
+  if (!isRecord(payload)) return 'Payload must be an object.';
+  if (endpoint === QQ_ENDPOINTS.status) return exactKeys(payload, []) ? null : 'connection.status does not accept fields.';
+  if (endpoint === QQ_ENDPOINTS.beginProvisioning) {
+    return exactKeys(payload, ['locale']) && (payload.locale === undefined || payload.locale === 'zh-CN')
+      ? null : 'provision.begin received unsupported fields.';
+  }
+  if ([QQ_ENDPOINTS.pollProvisioning, QQ_ENDPOINTS.cancelProvisioning].includes(endpoint)) {
+    return exactKeys(payload, ['attemptId']) && validId(payload.attemptId)
+      ? null : `${endpoint} requires an attemptId.`;
+  }
+  if (endpoint === QQ_ENDPOINTS.bindCredentials) {
+    return exactKeys(payload, ['appId', 'appSecret'])
+      && validCredential(payload.appId, 256)
+      && validCredential(payload.appSecret, 1024)
+      ? null : 'bot.bind-credentials requires AppID and AppSecret.';
+  }
+  if (endpoint === QQ_ENDPOINTS.reconnectBot) {
+    return exactKeys(payload, ['botId']) && validId(payload.botId) ? null : 'bot.reconnect requires a botId.';
+  }
+  if (endpoint === QQ_ENDPOINTS.deleteBot) {
+    return exactKeys(payload, ['botId', 'confirm']) && validId(payload.botId) && payload.confirm === true
+      ? null : 'bot.delete requires a botId and confirm=true.';
+  }
+  return 'Unknown QQ endpoint.';
+}
+
+function sanitizePublic(value) {
+  if (Array.isArray(value)) return value.map(sanitizePublic);
+  if (!isRecord(value)) return value;
+  const safe = {};
+  for (const [key, child] of Object.entries(value)) {
+    if (!FORBIDDEN_PUBLIC_KEYS.has(key)) safe[key] = sanitizePublic(child);
+  }
+  return safe;
+}
+
+async function qrDataUrl(value) {
+  return QRCode.toDataURL(value, {
+    type: 'image/png', errorCorrectionLevel: 'M', margin: 2, width: 320,
+  });
+}
+
+async function withEncodedQr(value, encodeQr) {
+  if (!value || typeof value.verificationUrl !== 'string') return sanitizePublic(value);
+  return sanitizePublic({ ...value, qrCodeDataUrl: await encodeQr(value.verificationUrl) });
+}
+
+async function publicStatus(status, encodeQr) {
+  const value = structuredClone(status);
+  if (value?.provisioning) value.provisioning = await withEncodedQr(value.provisioning, encodeQr);
+  return sanitizePublic(value);
+}
+
+export function createQqRpcHandler(controller, { encodeQr = qrDataUrl } = {}) {
+  for (const method of ['status', 'startProvisioning', 'registrationStatus', 'cancelProvisioning', 'bindCredentials', 'reconnectBot', 'deleteBot']) {
+    if (typeof controller?.[method] !== 'function') throw new TypeError(`A complete QQ controller is required (${method})`);
+  }
+  const qrCache = new Map();
+  const cachedEncode = (url) => {
+    let encoded = qrCache.get(url);
+    if (!encoded) {
+      if (qrCache.size >= 16) qrCache.delete(qrCache.keys().next().value);
+      encoded = Promise.resolve().then(() => encodeQr(url));
+      qrCache.set(url, encoded);
+    }
+    return encoded;
+  };
+  return async (endpoint, payload, signal) => {
+    if (signal?.aborted) return { ok: false, error: { code: 'cancelled', message: 'The request was cancelled.' } };
+    if (!QQ_RPC_ENDPOINTS.includes(endpoint)) return { ok: false, error: { code: 'bad-request', message: 'Unknown QQ endpoint.' } };
+    const invalid = payloadFailure(endpoint, payload);
+    if (invalid) return { ok: false, error: { code: 'bad-request', message: invalid } };
+    try {
+      let value;
+      if (endpoint === QQ_ENDPOINTS.status) value = await publicStatus(await controller.status(), cachedEncode);
+      else if (endpoint === QQ_ENDPOINTS.beginProvisioning) value = await withEncodedQr(await controller.startProvisioning(), cachedEncode);
+      else if (endpoint === QQ_ENDPOINTS.pollProvisioning) {
+        const current = await controller.registrationStatus(payload.attemptId);
+        if (!current) return { ok: false, error: { code: 'bad-request', message: 'The provisioning attempt no longer exists.' } };
+        value = await withEncodedQr(current, cachedEncode);
+      } else if (endpoint === QQ_ENDPOINTS.cancelProvisioning) {
+        value = sanitizePublic(await controller.cancelProvisioning(payload.attemptId));
+      } else if (endpoint === QQ_ENDPOINTS.bindCredentials) {
+        value = await publicStatus(await controller.bindCredentials(payload), cachedEncode);
+      } else if (endpoint === QQ_ENDPOINTS.reconnectBot) {
+        value = await publicStatus(await controller.reconnectBot(payload.botId), cachedEncode);
+      } else {
+        value = await publicStatus(await controller.deleteBot(payload.botId), cachedEncode);
+      }
+      return signal?.aborted
+        ? { ok: false, error: { code: 'cancelled', message: 'The request was cancelled.' } }
+        : { ok: true, value };
+    } catch {
+      return signal?.aborted
+        ? { ok: false, error: { code: 'cancelled', message: 'The request was cancelled.' } }
+        : { ok: false, error: { code: 'qq-operation-failed', message: 'QQ 操作失败，请稍后重试。' } };
+    }
+  };
+}
+
+export function installQqRpc(ctx, controller, options, authority) {
+  if (!ctx?.connection?.rpc || typeof ctx.connection.rpc.handle !== 'function') {
+    throw new TypeError('DSH Host Connection RPC is required');
+  }
+  return ctx.connection.rpc.handle(
+    QQ_RPC_CHANNEL,
+    createQqRpcHandler(controller, options),
+    { authority: resolveRpcAuthority(authority) },
+  );
+}

package/plugin-src/host/channels/shared/connection-supervisor.mjs

@@ -0,0 +1,133 @@
+const DEFAULT_RETRY_DELAYS_MS = Object.freeze([250, 1_000, 3_000, 5_000, 10_000, 30_000]);
+
+function retryDelays(value) {
+  if (!Array.isArray(value) || value.length === 0) return [...DEFAULT_RETRY_DELAYS_MS];
+  const valid = value.filter((delay) => Number.isFinite(delay) && delay >= 0);
+  return valid.length > 0 ? valid : [...DEFAULT_RETRY_DELAYS_MS];
+}
+
+export class TokenConnectionSupervisor {
+  #channel;
+  #controller;
+  #harness;
+  #logger;
+  #retryDelays;
+  #healthyIntervalMs;
+  #setTimeout;
+  #clearTimeout;
+  #timer = null;
+  #running = null;
+  #retryIndex = 0;
+  #closed = false;
+  #started = false;
+  #ready;
+  #resolveReady;
+
+  constructor({
+    channel,
+    controller,
+    harness,
+    logger = console,
+    retryDelaysMs,
+    healthyIntervalMs = 15_000,
+    setTimeoutImpl = setTimeout,
+    clearTimeoutImpl = clearTimeout,
+  }) {
+    if (!channel) throw new TypeError('TokenConnectionSupervisor requires a channel');
+    if (!controller || typeof controller.initialize !== 'function' || typeof controller.status !== 'function') {
+      throw new TypeError('TokenConnectionSupervisor requires a controller');
+    }
+    if (!harness || typeof harness.ensureRunning !== 'function') {
+      throw new TypeError('TokenConnectionSupervisor requires a Harness client');
+    }
+    this.#channel = channel;
+    this.#controller = controller;
+    this.#harness = harness;
+    this.#logger = logger;
+    this.#retryDelays = retryDelays(retryDelaysMs);
+    this.#healthyIntervalMs = Number.isFinite(healthyIntervalMs) && healthyIntervalMs >= 0
+      ? healthyIntervalMs : 15_000;
+    this.#setTimeout = setTimeoutImpl;
+    this.#clearTimeout = clearTimeoutImpl;
+    this.#ready = new Promise((resolve) => {
+      this.#resolveReady = resolve;
+    });
+  }
+
+  get ready() {
+    return this.#ready;
+  }
+
+  start() {
+    if (this.#started || this.#closed) return this;
+    this.#started = true;
+    this.#schedule(0);
+    return this;
+  }
+
+  async close() {
+    if (this.#closed) return;
+    this.#closed = true;
+    if (this.#timer !== null) this.#clearTimeout(this.#timer);
+    this.#timer = null;
+    await this.#running?.catch(() => undefined);
+    this.#resolveReady?.(null);
+    this.#resolveReady = null;
+  }
+
+  #schedule(delayMs) {
+    if (this.#closed) return;
+    this.#timer = this.#setTimeout(() => {
+      this.#timer = null;
+      void this.#run();
+    }, delayMs);
+    this.#timer?.unref?.();
+  }
+
+  async #run() {
+    if (this.#closed || this.#running) return;
+    const operation = this.#reconcile();
+    this.#running = operation;
+    try {
+      await operation;
+    } finally {
+      if (this.#running === operation) this.#running = null;
+    }
+  }
+
+  async #reconcile() {
+    try {
+      await this.#harness.ensureRunning();
+      if (this.#closed) return;
+      const status = await this.#controller.initialize();
+      if (this.#closed) return;
+      this.#resolveReady?.(status);
+      this.#resolveReady = null;
+      const { configured, connected } = status.totals;
+      if (connected < configured) {
+        const delay = this.#retryDelays[Math.min(this.#retryIndex, this.#retryDelays.length - 1)];
+        this.#retryIndex += 1;
+        this.#logger.warn?.(
+          `[dsh-im:${this.#channel}] ${connected}/${configured} bots connected; retrying in ${delay}ms`,
+        );
+        this.#schedule(delay);
+        return;
+      }
+      this.#retryIndex = 0;
+      this.#schedule(this.#healthyIntervalMs);
+    } catch (error) {
+      if (this.#closed) return;
+      const delay = this.#retryDelays[Math.min(this.#retryIndex, this.#retryDelays.length - 1)];
+      this.#retryIndex += 1;
+      this.#logger.warn?.(
+        `[dsh-im:${this.#channel}] connection reconciliation failed; retrying in ${delay}ms`,
+        error,
+      );
+      this.#schedule(delay);
+    }
+  }
+}
+
+export function createTokenConnectionSupervisor(options) {
+  return new TokenConnectionSupervisor(options);
+}

package/plugin-src/host/channels/shared/production.mjs

@@ -0,0 +1,104 @@
+import { unlink } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+import { createTokenConnectionSupervisor } from './connection-supervisor.mjs';
+
+function harnessOrigin(webServer, configured) {
+  if (configured !== undefined) return new URL(configured);
+  const port = webServer?.port;
+  if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+    throw new Error('dsh-im token channel requires an initialized DSH webServer port');
+  }
+  return new URL(`http://127.0.0.1:${port}`);
+}
+
+function pluginPaths(config, channel) {
+  const dshHome = resolve(config.dshHome ?? process.env.DSH_HOME ?? join(homedir(), '.dsh'));
+  const root = resolve(config.dataDir ?? join(dshHome, 'integrations', `dsh-${channel}`));
+  return {
+    config: resolve(config.configPath ?? join(root, 'config.json')),
+    bots: resolve(config.botsDir ?? join(root, 'bots')),
+  };
+}
+
+export async function createTokenProductionController(ctx, config, internals, definitions) {
+  const { channel, ConfigStore, StateStore, HarnessClient, Controller, Runtime } = definitions;
+  if (!ctx?.credentials) throw new TypeError(`dsh-im ${channel} requires ctx.credentials`);
+  if (!ctx?.webServer) throw new TypeError(`dsh-im ${channel} requires ctx.webServer`);
+
+  const ResolvedConfigStore = internals.ConfigStore ?? ConfigStore;
+  const ResolvedStateStore = internals.StateStore ?? StateStore;
+  const ResolvedHarness = internals.HarnessClient ?? HarnessClient;
+  const ResolvedController = internals.Controller ?? Controller;
+  const ResolvedRuntime = internals.Runtime ?? Runtime;
+  const createSupervisor = internals.createConnectionSupervisor ?? createTokenConnectionSupervisor;
+  const logger = typeof ctx.logger === 'function'
+    ? ctx.logger(`dsh-im:${channel}`) : (ctx.logger ?? console);
+  const paths = pluginPaths(config, channel);
+  const configStore = await new ResolvedConfigStore(paths.config).load();
+  const stateStores = new Map();
+  const statePath = (botId) => resolve(paths.bots, botId, 'state.json');
+  const stateFor = async (botId) => {
+    let state = stateStores.get(botId);
+    if (!state) {
+      state = await new ResolvedStateStore(statePath(botId)).load();
+      stateStores.set(botId, state);
+    }
+    return state;
+  };
+  const harness = new ResolvedHarness({
+    baseUrl: harnessOrigin(ctx.webServer, config.harnessBaseUrl),
+    workspace: resolve(config.workspace ?? process.cwd()),
+    agentPreset: config.agentPreset ?? 'standard',
+    autostart: false,
+    dshBin: config.dshBin ?? 'dsh',
+  });
+  const controller = new ResolvedController({
+    credentials: ctx.credentials,
+    configStore,
+    logger,
+    ...(internals.inspectToken ? { inspectToken: internals.inspectToken } : {}),
+    createRuntime: async ({ botId, config: botConfig, token }) => new ResolvedRuntime({
+      config: botConfig,
+      token,
+      harness,
+      state: await stateFor(botId),
+      replyTimeoutMs: config.replyTimeoutMs ?? 600_000,
+      connectTimeoutMs: config.connectTimeoutMs ?? 20_000,
+      logger: {
+        error: (...args) => logger.error?.(`[${botId}]`, ...args),
+        warn: (...args) => logger.warn?.(`[${botId}]`, ...args),
+        info: (...args) => logger.info?.(`[${botId}]`, ...args),
+        debug: (...args) => logger.debug?.(`[${botId}]`, ...args),
+      },
+    }),
+    deleteState: async ({ botId }) => {
+      const state = stateStores.get(botId);
+      stateStores.delete(botId);
+      if (state && typeof state.remove === 'function') return state.remove();
+      try {
+        await unlink(statePath(botId));
+      } catch (error) {
+        if (error?.code !== 'ENOENT') throw error;
+      }
+    },
+  });
+  const supervisor = createSupervisor({
+    channel,
+    controller,
+    harness,
+    logger,
+    retryDelaysMs: config.retryDelaysMs,
+    healthyIntervalMs: config.healthyIntervalMs,
+  }).start();
+  return {
+    controller,
+    ready: supervisor.ready,
+    async close() {
+      await supervisor.close();
+      await controller.close();
+      harness.stopManagedProcess();
+    },
+  };
+}

package/plugin-src/host/channels/shared/rpc.mjs

@@ -0,0 +1,119 @@
+import { resolveRpcAuthority } from '../../rpc-authority.mjs';
+
+export const TOKEN_BOT_ENDPOINTS = Object.freeze({
+  status: 'connection.status',
+  bindCredentials: 'bot.bind-credentials',
+  reconnectBot: 'bot.reconnect',
+  deleteBot: 'bot.delete',
+});
+
+const ENDPOINTS = Object.freeze(Object.values(TOKEN_BOT_ENDPOINTS));
+const FORBIDDEN_PUBLIC_KEYS = new Set([
+  'token', 'botToken', 'tokenRef', 'platformId', 'secret', 'secretRef',
+]);
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function exactKeys(value, allowed) {
+  return isRecord(value) && Object.keys(value).every((key) => allowed.includes(key));
+}
+
+function validId(value) {
+  return typeof value === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(value);
+}
+
+function validToken(value) {
+  return typeof value === 'string' && value.trim().length >= 20 && value.length <= 4_096;
+}
+
+function payloadFailure(endpoint, payload) {
+  if (!isRecord(payload)) return 'Payload must be an object.';
+  if (endpoint === TOKEN_BOT_ENDPOINTS.status) {
+    return exactKeys(payload, []) ? null : 'connection.status does not accept fields.';
+  }
+  if (endpoint === TOKEN_BOT_ENDPOINTS.bindCredentials) {
+    return exactKeys(payload, ['token']) && validToken(payload.token)
+      ? null : 'bot.bind-credentials requires a Bot Token.';
+  }
+  if (endpoint === TOKEN_BOT_ENDPOINTS.reconnectBot) {
+    return exactKeys(payload, ['botId']) && validId(payload.botId)
+      ? null : 'bot.reconnect requires a botId.';
+  }
+  if (endpoint === TOKEN_BOT_ENDPOINTS.deleteBot) {
+    return exactKeys(payload, ['botId', 'confirm']) && validId(payload.botId) && payload.confirm === true
+      ? null : 'bot.delete requires a botId and confirm=true.';
+  }
+  return 'Unknown bot endpoint.';
+}
+
+function sanitizePublic(value) {
+  if (Array.isArray(value)) return value.map(sanitizePublic);
+  if (!isRecord(value)) return value;
+  const safe = {};
+  for (const [key, child] of Object.entries(value)) {
+    if (!FORBIDDEN_PUBLIC_KEYS.has(key)) safe[key] = sanitizePublic(child);
+  }
+  return safe;
+}
+
+function operationError(channel, error) {
+  if (error?.code === 'webhook-configured') {
+    return { code: 'webhook-configured', message: error.message };
+  }
+  if (error?.code === 'telegram-401' || error?.code === 'discord-401') {
+    return { code: 'invalid-token', message: `${channel} Bot Token 无效，请重新填写。` };
+  }
+  if (error?.code === 'discord-intents') {
+    return { code: 'discord-intents', message: error.message };
+  }
+  return { code: `${channel.toLowerCase()}-operation-failed`, message: `${channel} 操作失败，请稍后重试。` };
+}
+
+export function createTokenBotRpcHandler(controller, { channel }) {
+  for (const method of ['status', 'bindCredentials', 'reconnectBot', 'deleteBot']) {
+    if (typeof controller?.[method] !== 'function') {
+      throw new TypeError(`A complete ${channel} controller is required (${method})`);
+    }
+  }
+  return async (endpoint, payload, signal) => {
+    if (signal?.aborted) {
+      return { ok: false, error: { code: 'cancelled', message: 'The request was cancelled.' } };
+    }
+    if (!ENDPOINTS.includes(endpoint)) {
+      return { ok: false, error: { code: 'bad-request', message: `Unknown ${channel} endpoint.` } };
+    }
+    const invalid = payloadFailure(endpoint, payload);
+    if (invalid) return { ok: false, error: { code: 'bad-request', message: invalid } };
+    try {
+      let value;
+      if (endpoint === TOKEN_BOT_ENDPOINTS.status) value = await controller.status();
+      else if (endpoint === TOKEN_BOT_ENDPOINTS.bindCredentials) {
+        value = await controller.bindCredentials(payload);
+      } else if (endpoint === TOKEN_BOT_ENDPOINTS.reconnectBot) {
+        value = await controller.reconnectBot(payload.botId);
+      } else {
+        value = await controller.deleteBot(payload.botId);
+      }
+      return signal?.aborted
+        ? { ok: false, error: { code: 'cancelled', message: 'The request was cancelled.' } }
+        : { ok: true, value: sanitizePublic(value) };
+    } catch (error) {
+      return signal?.aborted
+        ? { ok: false, error: { code: 'cancelled', message: 'The request was cancelled.' } }
+        : { ok: false, error: operationError(channel, error) };
+    }
+  };
+}
+
+export function installTokenBotRpc(ctx, controller, { channel, rpcChannel, authority }) {
+  if (!ctx?.connection?.rpc || typeof ctx.connection.rpc.handle !== 'function') {
+    throw new TypeError('DSH Host Connection RPC is required');
+  }
+  return ctx.connection.rpc.handle(
+    rpcChannel,
+    createTokenBotRpcHandler(controller, { channel }),
+    { authority: resolveRpcAuthority(authority) },
+  );
+}

package/plugin-src/host/channels/telegram/index.mjs

@@ -0,0 +1,30 @@
+import { createProductionController } from './production.mjs';
+import { installTelegramRpc } from './rpc.mjs';
+
+export const name = 'dsh-im-telegram-host';
+export const inject = ['connection', 'credentials', 'webServer'];
+
+export async function apply(ctx, config = {}) {
+  if (config?.controller) {
+    return installTelegramRpc(ctx, config.controller, config.rpcAuthority);
+  }
+  const production = await createProductionController(ctx, config, config.internals ?? {});
+  const disposeRpc = installTelegramRpc(ctx, production.controller, config.rpcAuthority);
+  ctx.effect(() => async () => production.close(), 'dsh-im: close Telegram bot connections');
+  return disposeRpc;
+}
+
+export function createTelegramHostPlugin(config) {
+  return Object.freeze({ name, inject, apply: (ctx) => apply(ctx, config) });
+}
+
+export { createProductionController } from './production.mjs';
+export {
+  TELEGRAM_ENDPOINTS,
+  TELEGRAM_RPC_CHANNEL,
+  TELEGRAM_RPC_ENDPOINTS,
+  createTelegramRpcHandler,
+  installTelegramRpc,
+} from './rpc.mjs';
+export { TelegramController } from '../../../../src/channels/telegram/telegram-controller.mjs';
+export { TelegramRuntime } from '../../../../src/channels/telegram/telegram-runtime.mjs';

package/plugin-src/host/channels/telegram/production.mjs

@@ -0,0 +1,17 @@
+import { TelegramConfigStore } from '../../../../src/channels/telegram/config-store.mjs';
+import { TelegramHarnessClient } from '../../../../src/channels/telegram/harness-client.mjs';
+import { TelegramController } from '../../../../src/channels/telegram/telegram-controller.mjs';
+import { TelegramRuntime } from '../../../../src/channels/telegram/telegram-runtime.mjs';
+import { TelegramStateStore } from '../../../../src/channels/telegram/state-store.mjs';
+import { createTokenProductionController } from '../shared/production.mjs';
+
+export function createProductionController(ctx, config = {}, internals = {}) {
+  return createTokenProductionController(ctx, config, internals, {
+    channel: 'telegram',
+    ConfigStore: TelegramConfigStore,
+    StateStore: TelegramStateStore,
+    HarnessClient: TelegramHarnessClient,
+    Controller: TelegramController,
+    Runtime: TelegramRuntime,
+  });
+}

package/plugin-src/host/channels/telegram/rpc.mjs

@@ -0,0 +1,21 @@
+import {
+  TOKEN_BOT_ENDPOINTS,
+  createTokenBotRpcHandler,
+  installTokenBotRpc,
+} from '../shared/rpc.mjs';
+
+export const TELEGRAM_RPC_CHANNEL = '/telegram';
+export const TELEGRAM_ENDPOINTS = TOKEN_BOT_ENDPOINTS;
+export const TELEGRAM_RPC_ENDPOINTS = Object.freeze(Object.values(TELEGRAM_ENDPOINTS));
+
+export function createTelegramRpcHandler(controller) {
+  return createTokenBotRpcHandler(controller, { channel: 'Telegram' });
+}
+
+export function installTelegramRpc(ctx, controller, authority) {
+  return installTokenBotRpc(ctx, controller, {
+    channel: 'Telegram',
+    rpcChannel: TELEGRAM_RPC_CHANNEL,
+    authority,
+  });
+}