@xmanrui/dsh-im 4.9.1 → 4.10.0

package/src/channels/feishu/feishu-channel.mjs

@@ -208,7 +208,7 @@ export class VerifiedFeishuChannel {
     let activeCard = null;
     let rotating = false;
     try {
-      activeCard = await this.#createStreamCard(chatId, options.replyTo);
+      activeCard = await this.#createStreamCard(chatId, options);
       cards.push(activeCard);
       let lastContent = this.#initialText;
       // issue #86：独立交互消息（提问/审批）落在占位卡下方后，最终答案不得
@@ -217,7 +217,7 @@ export class VerifiedFeishuChannel {
       // 交互消息之后。旧卡纳入 cards，参与 recall 与 providerMessageIds。
       const ensureActiveCard = async () => {
         if (!rotating) return activeCard;
-        activeCard = await this.#createStreamCard(chatId, options.replyTo);
+        activeCard = await this.#createStreamCard(chatId, options);
         cards.push(activeCard);
         rotating = false;
         return activeCard;
@@ -255,7 +255,7 @@ export class VerifiedFeishuChannel {
       for (const [index, chunk] of chunks.entries()) {
         const card = index === 0
           ? await ensureActiveCard()
-          : await this.#createStreamCard(chatId, options.replyTo);
+          : await this.#createStreamCard(chatId, options);
         if (index > 0) cards.push(card);
         await this.#updateStreamCard(card, chunk);
         await this.#finishStreamCard(card);
@@ -272,19 +272,33 @@ export class VerifiedFeishuChannel {
     }
   }
 
-  async sendFile(chatId, file, { replyTo, signal } = {}) {
+  async sendFile(chatId, file, {
+    replyTo,
+    signal,
+    replyInThread = false,
+    onReplyThreadId,
+  } = {}) {
     return this.#sendArtifact(chatId, file, {
       replyTo,
       signal,
+      replyInThread,
+      onReplyThreadId,
       messageType: 'file',
       presentation: 'feishu-file',
     });
   }
 
-  async sendImage(chatId, file, { replyTo, signal } = {}) {
+  async sendImage(chatId, file, {
+    replyTo,
+    signal,
+    replyInThread = false,
+    onReplyThreadId,
+  } = {}) {
     return this.#sendArtifact(chatId, file, {
       replyTo,
       signal,
+      replyInThread,
+      onReplyThreadId,
       messageType: 'image',
       presentation: 'feishu-image',
     });
@@ -293,6 +307,8 @@ export class VerifiedFeishuChannel {
   async #sendArtifact(chatId, file, {
     replyTo,
     signal,
+    replyInThread = false,
+    onReplyThreadId,
     messageType,
     presentation,
   }) {
@@ -349,7 +365,12 @@ export class VerifiedFeishuChannel {
     const request = replyTo
       ? {
           path: { message_id: replyTo },
-          data: { msg_type: messageType, content, uuid },
+          data: {
+            msg_type: messageType,
+            content,
+            uuid,
+            ...(replyInThread === true ? { reply_in_thread: true } : {}),
+          },
         }
       : {
           params: { receive_id_type: 'chat_id' },
@@ -399,6 +420,10 @@ export class VerifiedFeishuChannel {
     if (typeof messageId !== 'string' || !messageId) {
       throw fileDeliveryError('message send', undefined, undefined, { uncertain: true });
     }
+    if (replyTo && typeof onReplyThreadId === 'function') {
+      const threadId = response?.data?.thread_id;
+      if (typeof threadId === 'string' && threadId) await onReplyThreadId(threadId);
+    }
     return createDeliveryReceipt({
       deliveryId: file.deliveryKey,
       presentation,
@@ -410,7 +435,7 @@ export class VerifiedFeishuChannel {
     });
   }
 
-  async #createStreamCard(chatId, replyTo) {
+  async #createStreamCard(chatId, options = {}) {
     const content = streamPreview(this.#initialText);
     const response = assertApiSuccess('Feishu card.create', await this.#client.cardkit.v1.card.create({
       data: {
@@ -420,7 +445,7 @@ export class VerifiedFeishuChannel {
     }));
     const cardId = response?.data?.card_id;
     if (!cardId) throw new Error('Feishu card.create returned no card_id');
-    const messageId = await this.#sendCard(chatId, cardId, replyTo);
+    const messageId = await this.#sendCard(chatId, cardId, options);
     return { cardId, messageId, content, sequence: 0 };
   }
 
@@ -455,12 +480,18 @@ export class VerifiedFeishuChannel {
     assertApiSuccess('Feishu card.settings', response);
   }
 
-  async #sendCard(chatId, cardId, replyTo) {
+  async #sendCard(chatId, cardId, options = {}) {
+    const replyTo = options.replyTo;
+    const replyInThread = options.replyInThread === true;
     const content = JSON.stringify({ type: 'card', data: { card_id: cardId } });
     const response = replyTo
       ? await this.#client.im.v1.message.reply({
         path: { message_id: replyTo },
-        data: { msg_type: 'interactive', content },
+        data: {
+          msg_type: 'interactive',
+          content,
+          ...(replyInThread ? { reply_in_thread: true } : {}),
+        },
       })
       : await this.#client.im.v1.message.create({
         params: { receive_id_type: 'chat_id' },
@@ -469,6 +500,10 @@ export class VerifiedFeishuChannel {
     assertApiSuccess('Feishu message send', response);
     const messageId = response?.data?.message_id;
     if (!messageId) throw new Error('Feishu message send returned no message_id');
+    if (replyTo && typeof options.onReplyThreadId === 'function') {
+      const threadId = response?.data?.thread_id;
+      if (typeof threadId === 'string' && threadId) await options.onReplyThreadId(threadId);
+    }
     return messageId;
   }
 

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

@@ -110,6 +110,7 @@ export class FeishuRuntime {
   #domain;
   #botOpenId;
   #groupResponseMode;
+  #groupTopicReply;
   #ownerOpenIds;
   #harness;
   #state;
@@ -139,6 +140,7 @@ export class FeishuRuntime {
     domain = 'feishu',
     botOpenId,
     groupResponseMode,
+    groupTopicReply = false,
     ownerOpenId,
     ownerOpenIds,
     harness,
@@ -174,6 +176,7 @@ export class FeishuRuntime {
     this.#domain = domain;
     this.#botOpenId = nonEmptyString(botOpenId);
     this.#groupResponseMode = normalizeFeishuGroupResponseMode(groupResponseMode);
+    this.#groupTopicReply = groupTopicReply === true;
     this.#ownerOpenIds = normalizedOwners;
     this.#harness = harness;
     this.#state = state;
@@ -198,6 +201,11 @@ export class FeishuRuntime {
     this.#bridge?.setGroupResponseMode(this.#groupResponseMode);
   }
 
+  setGroupTopicReply(value) {
+    this.#groupTopicReply = value === true;
+    this.#bridge?.setGroupTopicReply(this.#groupTopicReply);
+  }
+
   async start() {
     while (true) {
       while (this.#stopping) await this.#stopping;
@@ -286,6 +294,7 @@ export class FeishuRuntime {
         appId: this.#appId,
         botOpenId: this.#botOpenId,
         groupResponseMode: this.#groupResponseMode,
+        groupTopicReply: this.#groupTopicReply,
         repair: this.#repair,
         replyTimeoutMs: this.#replyTimeoutMs,
         // Interaction cards (approval/question buttons) are on by default.

package/src/channels/feishu/message-utils.mjs

@@ -13,6 +13,19 @@ const FEISHU_CARD_UNAVAILABLE_TEXTS = new Set([
 const FEISHU_IMAGE_PERMISSION_MESSAGE =
   '飞书机器人缺少图片读取权限 im:message:readonly（飞书显示为“获取单聊、群组消息”）。请私聊机器人执行 /repair 命令，或者在「IM机器人」设置页点击“补全权限”按钮并扫码。按飞书提示发布新版本、完成必要审批后，再重新发送图片。';
 
+/** Managed-topic group key: one per Feishu topic auto-rooted at a message. */
+export function managedGroupKey(chatId, rootMessageId) {
+  if (!chatId) throw new Error('Feishu managed-topic key needs a chat_id');
+  if (!rootMessageId) throw new Error('Feishu managed-topic key needs a root message id');
+  return `group:${chatId}:managed:${rootMessageId}`;
+}
+
+/** Whether a key denotes a topic-isolated group conversation (thread or managed). */
+export function isTopicGroupKey(key) {
+  return typeof key === 'string' && key.startsWith('group:')
+    && (key.includes(':thread:') || key.includes(':managed:'));
+}
+
 export function conversationKey(event) {
   const chatType = event?.message?.chat_type;
   if (chatType === 'p2p') {

package/src/channels/feishu/multi-bot-controller.mjs

@@ -90,6 +90,7 @@ function configuredBotFingerprint(config) {
     botOpenId: config.botOpenId,
     activated: config.activated,
     groupResponseMode: normalizeFeishuGroupResponseMode(config.groupResponseMode),
+    groupTopicReply: config.groupTopicReply === true,
     groupMessagePermissionGranted: config.groupMessagePermissionGranted === true,
     deletionPending: config.deletionPending === true,
     connectedAt: config.connectedAt ?? null,
@@ -584,6 +585,20 @@ export class MultiBotDshFeishuController {
     }));
   }
 
+  async updateGroupTopicReply(botId, groupTopicReply) {
+    this.#assertOpen();
+    if (typeof groupTopicReply !== 'boolean') {
+      throw new TypeError('Invalid Feishu group topic reply flag');
+    }
+    return this.#serializeConfig(() => this.#withBotTransition(botId, async () => {
+      const config = this.#requireBot(botId);
+      const saved = await this.#configStore.saveBot({ ...config, groupTopicReply });
+      this.#runtimes.get(botId)?.setGroupTopicReply?.(saved.groupTopicReply);
+      this.#touch();
+      return this.status(botId);
+    }));
+  }
+
   async deleteBot(botId) {
     this.#assertOpen();
     return this.#serializeConfig(() => this.#withBotTransition(botId, async () => {
@@ -646,6 +661,7 @@ export class MultiBotDshFeishuController {
         connected,
         configured: true,
         groupResponseMode: normalizeFeishuGroupResponseMode(config.groupResponseMode),
+        groupTopicReply: config.groupTopicReply === true,
         groupMessagePermissionGranted: config.groupMessagePermissionGranted === true,
         bot: publicBot(config),
         connection,

package/src/channels/feishu/plugin-config-store.mjs

@@ -45,6 +45,7 @@ function normalizeBot(value, { legacy = false } = {}) {
     botOpenId: cleanString(value.botOpenId),
     activated: value.activated ?? null,
     groupResponseMode: normalizeFeishuGroupResponseMode(value.groupResponseMode),
+    groupTopicReply: value.groupTopicReply === true,
     groupMessagePermissionGranted: value.groupMessagePermissionGranted === true,
     deletionPending: value.deletionPending === true,
     connectedAt: cleanString(value.connectedAt),

package/src/channels/feishu/state-store.mjs

@@ -7,6 +7,7 @@ const EMPTY_STATE = Object.freeze({
   seenMessageIds: [],
   watches: {},
   includeArchivedSessions: false,
+  topics: {},
 });
 
 /** One conversation key may watch at most this many sessions. */
@@ -40,6 +41,7 @@ export class StateStore {
         includeArchivedSessions: typeof parsed.includeArchivedSessions === 'boolean'
           ? parsed.includeArchivedSessions
           : false,
+        topics: parsed.topics && typeof parsed.topics === 'object' ? parsed.topics : {},
       };
     } catch (error) {
       if (error?.code !== 'ENOENT') throw error;
@@ -136,6 +138,29 @@ export class StateStore {
     return [...ids];
   }
 
+  // ── Managed Feishu topics (thread_id → root message, persisted) ────────
+
+  topicRootFor(threadId) {
+    const entry = this.#state.topics[threadId];
+    return entry && typeof entry === 'object'
+      && typeof entry.rootMessageId === 'string' && entry.rootMessageId.length > 0
+      && typeof entry.chatId === 'string' && entry.chatId.length > 0
+      ? { rootMessageId: entry.rootMessageId, chatId: entry.chatId }
+      : null;
+  }
+
+  async setTopic(threadId, root) {
+    const validRoot = root && typeof root === 'object'
+      && typeof root.rootMessageId === 'string' && root.rootMessageId.length > 0
+      && typeof root.chatId === 'string' && root.chatId.length > 0;
+    if (!validRoot) throw new TypeError('Invalid Feishu topic root');
+    this.#state.topics[threadId] = {
+      rootMessageId: root.rootMessageId,
+      chatId: root.chatId,
+    };
+    await this.#persist();
+  }
+
   // ── Session-list archived policy (per bot) ───────────────────
 
   includesArchivedSessions() {

package/src/channels/shared/bot-workspace-store.mjs

@@ -323,6 +323,12 @@ export class BotWorkspaceStore {
     return Object.hasOwn(this.#workspaces, id) && !this.#removals.has(id);
   }
 
+  listBotIds() {
+    return Object.keys(this.#workspaces)
+      .filter((botId) => !this.#removals.has(botId))
+      .sort();
+  }
+
   incarnationFor(botId) {
     return this.#incarnations.get(botIdOf(botId)) ?? null;
   }

package/src/channels/shared/inbound-file.mjs

@@ -1,11 +1,40 @@
 import { createWriteStream } from 'node:fs';
-import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { mkdir, mkdtemp, readdir, realpath, rm, writeFile } from 'node:fs/promises';
 import { isAbsolute, join, relative, resolve } from 'node:path';
 import { pipeline } from 'node:stream/promises';
 
 import { t } from './i18n.mjs';
 
 const FILES_DIRECTORY = join('.dsh-im', 'inbound');
+const RETENTIONS = new Set(['turn', 'persistent']);
+const DIRECTORY_TIMESTAMP_PATTERN = /^(\d{4})(\d{2})(\d{2})-(\d{2})(\d{2})(\d{2})/;
+
+function padded(value) {
+  return String(value).padStart(2, '0');
+}
+
+/** Timestamp prefix (`yyyyMMdd-HHmmss-`) handed to mkdtemp for random suffixes. */
+function inboundDirectoryPrefix(now = new Date()) {
+  return `${now.getFullYear()}${padded(now.getMonth() + 1)}${padded(now.getDate())}`
+    + `-${padded(now.getHours())}${padded(now.getMinutes())}${padded(now.getSeconds())}-`;
+}
+
+/**
+ * Parse the local-time instant encoded in a staged inbound directory name,
+ * returning null for legacy `turn-` names and anything unparseable.
+ */
+export function parseInboundDirectoryName(name) {
+  if (typeof name !== 'string') return null;
+  const match = DIRECTORY_TIMESTAMP_PATTERN.exec(name);
+  if (!match) return null;
+  const [year, month, day, hour, minute, second] = match.slice(1).map(Number);
+  const date = new Date(year, month - 1, day, hour, minute, second);
+  if (date.getFullYear() !== year || date.getMonth() !== month - 1 || date.getDate() !== day
+    || date.getHours() !== hour || date.getMinutes() !== minute || date.getSeconds() !== second) {
+    return null;
+  }
+  return date;
+}
 
 export class InboundFileError extends Error {
   constructor(code, message, userMessage = t('文件接收失败，请重新发送后再试。'), options = {}) {
@@ -97,7 +126,18 @@ export function prefetchInboundFiles(message, { signal } = {}) {
 export async function stageInboundFiles(message, {
   workspace,
   signal,
+  retention = 'turn',
+  onStagedDirectory = null,
 } = {}) {
+  if (!RETENTIONS.has(retention)) {
+    throw new InboundFileError(
+      'inbound-file-retention-invalid',
+      `Unknown inbound file retention: ${String(retention)}`,
+    );
+  }
+  if (onStagedDirectory !== null && typeof onStagedDirectory !== 'function') {
+    throw new TypeError('onStagedDirectory must be a function');
+  }
   const sources = fileSources(message);
   if (sources.length === 0) return null;
   if (typeof workspace !== 'string' || !isAbsolute(workspace)) {
@@ -110,7 +150,10 @@ export async function stageInboundFiles(message, {
   signal?.throwIfAborted();
   const root = resolve(workspace, FILES_DIRECTORY);
   await mkdir(root, { recursive: true, mode: 0o700 });
-  const directory = await mkdtemp(join(root, 'turn-'));
+  const directory = await mkdtemp(join(root, inboundDirectoryPrefix()));
+  // Register the batch before any file is written so a concurrent TTL=0
+  // sweep can never observe the directory as untracked mid-staging.
+  onStagedDirectory?.(directory);
   const files = [];
 
   try {
@@ -177,7 +220,11 @@ export async function stageInboundFiles(message, {
     }
     return Object.freeze({
       files: Object.freeze(files),
+      directory,
+      retention,
       async cleanup() {
+        // Persistent retention leaves the directory to the global TTL sweeper.
+        if (retention !== 'turn') return;
         await rm(directory, { recursive: true, force: true });
       },
     });
@@ -187,6 +234,74 @@ export async function stageInboundFiles(message, {
   }
 }
 
+/**
+ * Delete expired staged inbound directories under one workspace. Only
+ * directories whose names parse as `yyyyMMdd-HHmmss` timestamps are managed;
+ * legacy `turn-` names and anything unparseable stay untouched. Directories
+ * reported as tracked by an in-flight turn are always skipped.
+ */
+export async function sweepInboundAttachments(workspace, ttlHours, {
+  now = () => new Date(),
+  isTracked,
+} = {}) {
+  if (typeof workspace !== 'string' || !workspace) {
+    throw new TypeError('sweepInboundAttachments requires a workspace');
+  }
+  // An unparsable TTL must never widen into unconditional deletion.
+  if (ttlHours !== 0 && !(Number.isInteger(ttlHours) && ttlHours > 0)) {
+    return { deleted: 0 };
+  }
+  const root = resolve(workspace, FILES_DIRECTORY);
+  let canonicalWorkspace;
+  let canonicalRoot;
+  try {
+    [canonicalWorkspace, canonicalRoot] = await Promise.all([
+      realpath(workspace),
+      realpath(root),
+    ]);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { deleted: 0 };
+    throw error;
+  }
+  const rootInWorkspace = relative(canonicalWorkspace, canonicalRoot);
+  if (!rootInWorkspace || rootInWorkspace.startsWith('..') || isAbsolute(rootInWorkspace)) {
+    throw new InboundFileError(
+      'inbound-file-root-outside-workspace',
+      'The inbound attachment directory does not resolve inside the Harness Session workspace.',
+    );
+  }
+  let entries;
+  try {
+    entries = await readdir(canonicalRoot, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { deleted: 0 };
+    throw error;
+  }
+  const current = now();
+  let deleted = 0;
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const stagedAt = parseInboundDirectoryName(entry.name);
+    if (stagedAt === null) continue;
+    const directory = join(root, entry.name);
+    const canonicalDirectory = join(canonicalRoot, entry.name);
+    if (typeof isTracked === 'function'
+      && (isTracked(directory) || (directory !== canonicalDirectory && isTracked(canonicalDirectory)))) {
+      continue;
+    }
+    const ageHours = (current - stagedAt) / 3_600_000;
+    if (ttlHours === 0 || ageHours >= ttlHours) {
+      try {
+        await rm(canonicalDirectory, { recursive: true, force: true });
+        deleted += 1;
+      } catch {
+        // One undeletable directory must not abort the remaining sweep.
+      }
+    }
+  }
+  return { deleted };
+}
+
 export function appendInboundFilesToPrompt(prompt, staged) {
   if (!staged?.files?.length) return prompt;
   const manifest = [

package/src/channels/shared/inbound-ttl-store.mjs

@@ -0,0 +1,110 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+
+import { DEFAULT_INBOUND_TTL_HOURS, normalizeInboundTtlHours } from './inbound-ttl.mjs';
+
+const DOCUMENT_VERSION = 1;
+// Fail-safe TTL for documents that exist but cannot be trusted (damage or an
+// unknown future version, e.g. after a rollback). TTL 0 would sweep every
+// untracked directory on the next pass, so keep-forever is the safe fallback.
+const UNREADABLE_DOCUMENT_TTL_HOURS = -1;
+
+function invalidTtlError() {
+  const error = new Error('Invalid inbound attachment TTL hours.');
+  error.code = 'inbound-ttl-invalid';
+  return error;
+}
+
+// Mirrors the atomic settings writes of the bot workspace store and the
+// update service: create a private temporary file, then rename it into place.
+async function writeSettingsDocument(path, document) {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(document, null, 2)}\n`, {
+      encoding: 'utf8',
+      mode: 0o600,
+      flag: 'wx',
+    });
+    await rename(temporary, path);
+  } finally {
+    await unlink(temporary).catch((error) => {
+      if (error.code !== 'ENOENT') throw error;
+    });
+  }
+}
+
+/** Durable host-side settings for the global inbound attachment TTL. */
+export class InboundTtlStore {
+  #path;
+  #ttlHours = DEFAULT_INBOUND_TTL_HOURS;
+
+  constructor(path) {
+    if (typeof path !== 'string' || !path) throw new TypeError('inbound TTL store path is required');
+    this.#path = path;
+  }
+
+  /**
+   * A missing file means first run (default TTL). A damaged or future
+   * document falls back to keep-forever so an unreadable intent can never
+   * widen into deletion; the value stays visible in the settings UI.
+   */
+  async load() {
+    let raw;
+    try {
+      raw = await readFile(this.#path, 'utf8');
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+      this.#ttlHours = DEFAULT_INBOUND_TTL_HOURS;
+      await this.#removeStaleTemporaries();
+      return this;
+    }
+    this.#ttlHours = this.#readTtlHours(raw) ?? UNREADABLE_DOCUMENT_TTL_HOURS;
+    await this.#removeStaleTemporaries();
+    return this;
+  }
+
+  // Crash leftovers from an interrupted atomic write are unreferenced by
+  // anyone; remove them so the settings directory stays clean.
+  async #removeStaleTemporaries() {
+    const directory = dirname(this.#path);
+    const prefix = `${basename(this.#path)}.`;
+    try {
+      const entries = await readdir(directory);
+      await Promise.all(entries
+        .filter((name) => name.startsWith(prefix) && name.endsWith('.tmp'))
+        .map((name) => unlink(join(directory, name)).catch(() => {})));
+    } catch {
+      // A missing directory or concurrent removal is fine; cleanup is best-effort.
+    }
+  }
+
+  #readTtlHours(raw) {
+    let document;
+    try {
+      document = JSON.parse(raw);
+    } catch {
+      return null;
+    }
+    if (!document || typeof document !== 'object' || Array.isArray(document)) return null;
+    if (document.version !== DOCUMENT_VERSION) return null;
+    if (document.inboundAttachmentTtlHours === undefined) return DEFAULT_INBOUND_TTL_HOURS;
+    return normalizeInboundTtlHours(document.inboundAttachmentTtlHours);
+  }
+
+  getTtlHours() {
+    return this.#ttlHours;
+  }
+
+  async setTtlHours(value) {
+    const ttlHours = normalizeInboundTtlHours(value);
+    if (ttlHours === null) throw invalidTtlError();
+    await writeSettingsDocument(this.#path, {
+      version: DOCUMENT_VERSION,
+      inboundAttachmentTtlHours: ttlHours,
+    });
+    this.#ttlHours = ttlHours;
+    return ttlHours;
+  }
+}

package/src/channels/shared/inbound-ttl.mjs

@@ -0,0 +1,22 @@
+export const DEFAULT_INBOUND_TTL_HOURS = 168;
+export const INBOUND_TTL_MAX_HOURS = 8760;
+
+const INTEGER_STRING = /^[+-]?\d+$/;
+
+/**
+ * Normalize a global inbound attachment TTL. Valid values are -1 (keep
+ * forever), 0 (delete once the owning turn ends), and whole hours 1..8760.
+ * Integer strings are tolerated; every other input returns null.
+ */
+export function normalizeInboundTtlHours(value) {
+  let candidate = value;
+  if (typeof candidate === 'string') {
+    const trimmed = candidate.trim();
+    if (!INTEGER_STRING.test(trimmed)) return null;
+    candidate = Number(trimmed);
+  }
+  if (typeof candidate !== 'number' || !Number.isInteger(candidate)) return null;
+  if (candidate === -1) return -1;
+  if (candidate >= 0 && candidate <= INBOUND_TTL_MAX_HOURS) return candidate;
+  return null;
+}