@llblab/pi-telegram 0.54.3 → 0.55.0

package/lib/runtime.ts

@@ -4,6 +4,8 @@
  * Owns small session-local runtime primitives that are shared by orchestration but are not specific to queueing, rendering, polling, or Telegram transport
  */
 
+import * as Machine from "./machine.ts";
+
 const TELEGRAM_TYPING_ACTION_INTERVAL_MS = 3_000;
 const TELEGRAM_TYPING_IDLE_DRAIN_MAX_MS = 250;
 
@@ -23,10 +25,6 @@ export interface TelegramRuntimeLifecycleFlags {
 export interface TelegramBridgeRuntimeState
   extends TelegramRuntimeQueueCounters, TelegramRuntimeLifecycleFlags {
   abortHandler?: () => void;
-  typingInterval?: ReturnType<typeof setInterval>;
-  typingInFlight?: Promise<void>;
-  typingLoopDeps?: TelegramTypingLoopDeps;
-  typingLoopKey?: string;
 }
 
 export interface TelegramRuntimeQueuePort {
@@ -66,7 +64,8 @@ export interface TelegramRuntimeAbortPort {
 export interface TelegramRuntimeTypingPort {
   start: (deps: TelegramTypingLoopDeps) => boolean;
   stop: () => boolean;
-  waitForIdle: () => Promise<void>;
+  /** Waits for the in-flight action, bounded so a never-settling request cannot hold shutdown. */
+  waitForIdle: (timeoutMs?: number) => Promise<void>;
 }
 
 export interface TelegramBridgeRuntime {
@@ -92,6 +91,7 @@ export function createTelegramBridgeRuntimeState(): TelegramBridgeRuntimeState {
 
 export function createTelegramBridgeRuntime(
   state = createTelegramBridgeRuntimeState(),
+  typing = createTelegramTypingLoop(),
 ): TelegramBridgeRuntime {
   return {
     state,
@@ -132,11 +132,7 @@ export function createTelegramBridgeRuntime(
       getHandler: () => getTelegramAbortHandler(state),
       abortTurn: () => abortTelegramTurn(state),
     },
-    typing: {
-      start: (deps) => startTelegramTypingLoop(state, deps),
-      stop: () => stopTelegramTypingLoop(state),
-      waitForIdle: () => waitForTelegramTypingLoopIdle(state),
-    },
+    typing,
   };
 }
 
@@ -302,15 +298,6 @@ export interface TelegramTypingLoopTarget {
   threadId?: number;
 }
 
-function getTelegramTypingLoopThreadParams(
-  target: TelegramTypingLoopTarget | undefined,
-): { message_thread_id?: number } | undefined {
-  const threadId = target?.threadId;
-  return Number.isInteger(threadId)
-    ? { message_thread_id: threadId }
-    : undefined;
-}
-
 export interface TelegramTypingLoopDeps {
   chatId: number | undefined;
   target?: TelegramTypingLoopTarget;
@@ -361,11 +348,13 @@ export interface TelegramTypingLoopStarterDeps<
   getDefaultChatId: () => number | undefined;
   sendTypingAction: (
     chatId: number,
-    options?: { message_thread_id?: number },
+    options?: { message_thread_id?: number; assertAuthority?: () => void },
   ) => Promise<unknown>;
   updateStatus: (ctx: TContext, error?: string) => void;
   isContextActive?: (ctx: TContext) => boolean;
+  getSessionGeneration?: () => number;
   isTransportAvailable?: () => boolean;
+  isThreadedMode?: () => boolean;
   getTransportAuthority?: () => string | number | undefined;
   intervalMs?: number;
 }
@@ -378,30 +367,43 @@ export function createTelegramTypingLoopStarter<TContext>(
   options?: { target?: TelegramTypingLoopTarget },
 ) => boolean {
   return (ctx, chatId, options) => {
+    const sessionGeneration = deps.getSessionGeneration?.();
     const transportAuthority = deps.getTransportAuthority?.();
+    const isContextCurrent = (): boolean => deps.isContextActive?.(ctx) !== false &&
+      (!deps.getSessionGeneration || Object.is(deps.getSessionGeneration(), sessionGeneration));
     const hasTransport = (): boolean =>
       deps.getTransportAuthority
         ? transportAuthority !== undefined &&
           Object.is(deps.getTransportAuthority(), transportAuthority)
         : deps.isTransportAvailable?.() !== false;
-    if (!hasTransport()) return false;
+    const target = options?.target ? { ...options.target } : undefined;
+    const canContinue = (): boolean => isContextCurrent() && hasTransport() &&
+      (deps.isThreadedMode?.() !== true ||
+        (target?.threadId !== undefined && Number.isSafeInteger(target.threadId) && target.threadId > 0));
+    // Queue dispatch precedes agent_start: only an explicit destination permits Threaded presence, never chat fallback.
+    if (!canContinue()) return false;
     let active = true;
     return deps.typing.start({
       chatId: chatId ?? deps.getDefaultChatId(),
-      target: options?.target,
+      target,
       intervalMs: deps.intervalMs ?? TELEGRAM_TYPING_ACTION_INTERVAL_MS,
       sendTypingAction: async (targetChatId, actionOptions) => {
         if (!active) return;
-        if (!hasTransport()) {
+        if (!canContinue()) {
           deps.typing.stop();
           return;
         }
         try {
-          await deps.sendTypingAction(targetChatId, actionOptions);
+          await deps.sendTypingAction(targetChatId, {
+            ...actionOptions,
+            // This stays process-local; adapters recheck it before HTTP/IPC issuance, not just loop ticks.
+            assertAuthority() {
+              if (!active || !canContinue()) throw new Error("Typing context authority changed.");
+            },
+          });
         } catch (error) {
-          if (deps.isContextActive?.(ctx) === false) return;
           if (!active) return;
-          if (!hasTransport()) {
+          if (!canContinue()) {
             deps.typing.stop();
             return;
           }
@@ -414,7 +416,7 @@ export function createTelegramTypingLoopStarter<TContext>(
           }
         }
       },
-      shouldContinue: hasTransport,
+      shouldContinue: canContinue,
       onStopped: () => {
         active = false;
       },
@@ -427,85 +429,239 @@ function getTelegramTypingLoopKey(deps: TelegramTypingLoopDeps): string {
   return `${deps.chatId ?? 0}:${Number.isInteger(threadId) ? threadId : "all"}`;
 }
 
-export function startTelegramTypingLoop(
-  state: TelegramBridgeRuntimeState,
-  deps: TelegramTypingLoopDeps,
-): boolean {
-  if (deps.chatId === undefined || deps.chatId === 0) return false;
-  const previousKey = state.typingLoopKey;
-  const previousDeps = state.typingLoopDeps;
-  const nextKey = getTelegramTypingLoopKey(deps);
-  if (previousDeps && previousDeps !== deps) {
-    previousDeps.onStopped?.();
-    state.typingInFlight = undefined;
-  }
-  state.typingLoopDeps = deps;
-  state.typingLoopKey = nextKey;
-  const sendTyping = (): void => {
-    const activeDeps = state.typingLoopDeps;
-    if (
-      !activeDeps ||
-      activeDeps.chatId === undefined ||
-      activeDeps.chatId === 0
-    )
-      return;
-    if (activeDeps.shouldContinue?.() === false) {
-      stopTelegramTypingLoop(state);
-      return;
+/** The whole typing-loop state; only `transitionTelegramTypingLoop` produces a new one. */
+export interface TelegramTypingMachineState {
+  /** The loop the interval serves; its callbacks live in the shell under `id`. A loop exists exactly while ticking. */
+  readonly loop: {
+    readonly id: number;
+    readonly key: string;
+    readonly chatId: number;
+    readonly threadParams?: { readonly message_thread_id: number };
+  } | null;
+  /** The action in flight; a tick waits for it, and replacing or stopping the loop forgets it. */
+  readonly inFlight: number | null;
+  readonly nextSendId: number;
+}
+
+export type TelegramTypingEvent =
+  | {
+      type: "started";
+      /** Shell-assigned, so the shell can hold the caller's callbacks before effects run. */
+      loopId: number;
+      chatId: number | undefined;
+      key: string;
+      threadParams?: { message_thread_id: number };
+      intervalMs: number;
+      /** The caller's `shouldContinue`, sampled at dispatch. */
+      continues: boolean;
     }
-    if (state.typingInFlight) return;
-    const targetChatId = activeDeps.chatId;
-    const threadParams = getTelegramTypingLoopThreadParams(activeDeps.target);
-    const typing = Promise.resolve()
-      .then(() => activeDeps.sendTypingAction(targetChatId, threadParams))
-      .then(() => undefined)
-      .catch(() => undefined);
-    state.typingInFlight = typing;
-    void typing.finally(() => {
-      if (state.typingInFlight === typing) state.typingInFlight = undefined;
-    });
-  };
-  if (state.typingInterval) {
-    if (previousKey === nextKey) return false;
-    sendTyping();
-    return true;
-  }
-  sendTyping();
-  state.typingInterval = setInterval(sendTyping, deps.intervalMs);
-  state.typingInterval.unref?.();
-  return true;
+  | { type: "ticked"; continues: boolean }
+  | { type: "sendSettled"; sendId: number }
+  | { type: "stopRequested" };
+
+export type TelegramTypingEffect =
+  | {
+      type: "send";
+      loopId: number;
+      sendId: number;
+      chatId: number;
+      threadParams?: { message_thread_id: number };
+    }
+  | { type: "armInterval"; intervalMs: number }
+  | { type: "cancelInterval" }
+  | { type: "loopEnded"; loopId: number };
+
+export interface TelegramTypingStep extends Machine.TelegramMachineStep<
+  TelegramTypingMachineState,
+  TelegramTypingEffect
+> {
+  /** `start`: a loop began or moved to a new target. `stop`: a running loop ended. */
+  result: boolean;
+}
+
+export function createTelegramTypingMachineState(): TelegramTypingMachineState {
+  return { loop: null, inFlight: null, nextSendId: 0 };
+}
+
+const typingStep = (
+  state: TelegramTypingMachineState,
+  result: boolean,
+  ...effects: TelegramTypingEffect[]
+): TelegramTypingStep => ({ state, effects, result });
+
+function stopTypingLoop(state: TelegramTypingMachineState): TelegramTypingStep {
+  if (!state.loop) return typingStep(state, false);
+  return typingStep(
+    { ...state, loop: null, inFlight: null },
+    true,
+    { type: "cancelInterval" },
+    { type: "loopEnded", loopId: state.loop.id },
+  );
+}
+
+/** One action per tick, never two at once; a caller that stops continuing ends the loop instead. */
+function sendTypingAction(
+  state: TelegramTypingMachineState,
+  continues: boolean,
+): TelegramTypingStep {
+  const loop = state.loop;
+  if (!loop) return typingStep(state, false);
+  if (!continues) return stopTypingLoop(state);
+  if (state.inFlight !== null) return typingStep(state, false);
+  const sendId = state.nextSendId + 1;
+  return typingStep({ ...state, inFlight: sendId, nextSendId: sendId }, false, {
+    type: "send",
+    loopId: loop.id,
+    sendId,
+    chatId: loop.chatId,
+    ...(loop.threadParams ? { threadParams: loop.threadParams } : {}),
+  });
 }
 
-export function stopTelegramTypingLoop(
-  state: TelegramBridgeRuntimeState,
-): boolean {
-  if (!state.typingInterval) return false;
-  clearInterval(state.typingInterval);
-  const activeDeps = state.typingLoopDeps;
-  state.typingInterval = undefined;
-  state.typingLoopDeps = undefined;
-  state.typingLoopKey = undefined;
-  state.typingInFlight = undefined;
-  activeDeps?.onStopped?.();
-  return true;
+/**
+ * Pure typing-loop transition. Every start replaces the caller's callbacks, even on the same target, and forgets the
+ * old in-flight action; only a new target sends at once on a running loop, whose interval keeps its phase.
+ */
+export function transitionTelegramTypingLoop(
+  state: TelegramTypingMachineState,
+  event: TelegramTypingEvent,
+): TelegramTypingStep {
+  switch (event.type) {
+    case "started": {
+      if (event.chatId === undefined || event.chatId === 0)
+        return typingStep(state, false);
+      const previous = state.loop;
+      const replaced: TelegramTypingEffect[] = previous
+        ? [{ type: "loopEnded", loopId: previous.id }]
+        : [];
+      const next: TelegramTypingMachineState = {
+        ...state,
+        inFlight: previous ? null : state.inFlight,
+        loop: {
+          id: event.loopId,
+          key: event.key,
+          chatId: event.chatId,
+          ...(event.threadParams ? { threadParams: event.threadParams } : {}),
+        },
+      };
+      if (previous?.key === event.key)
+        return typingStep(next, false, ...replaced);
+      if (previous) {
+        const sent = sendTypingAction(next, event.continues);
+        return typingStep(sent.state, true, ...replaced, ...sent.effects);
+      }
+      // A fresh loop always arms its interval; a caller that already stopped continuing ends it on the first tick.
+      const sent = event.continues
+        ? sendTypingAction(next, true)
+        : typingStep(next, false);
+      return typingStep(sent.state, true, ...sent.effects, {
+        type: "armInterval",
+        intervalMs: event.intervalMs,
+      });
+    }
+    case "ticked":
+      return sendTypingAction(state, event.continues);
+    case "sendSettled":
+      return typingStep(
+        state.inFlight === event.sendId ? { ...state, inFlight: null } : state,
+        false,
+      );
+    case "stopRequested":
+      return stopTypingLoop(state);
+  }
 }
 
-export async function waitForTelegramTypingLoopIdle(
-  state: TelegramBridgeRuntimeState,
-  timeoutMs = TELEGRAM_TYPING_IDLE_DRAIN_MAX_MS,
-): Promise<void> {
-  const inFlight = state.typingInFlight;
-  if (!inFlight) return;
-  if (timeoutMs <= 0) {
-    await Promise.race([inFlight, Promise.resolve()]);
-    return;
-  }
-  await Promise.race([
-    inFlight,
-    new Promise<void>((resolve) => {
-      setTimeout(resolve, timeoutMs);
-    }),
-  ]);
+/**
+ * The shell around `transitionTelegramTypingLoop`: it holds each loop's callbacks, samples `shouldContinue` into
+ * events, owns the interval and turns every action outcome into `sendSettled`.
+ */
+export function createTelegramTypingLoop(): TelegramRuntimeTypingPort {
+  const callbacks = new Map<number, TelegramTypingLoopDeps>();
+  let interval: ReturnType<typeof setInterval> | undefined;
+  let loopIds = 0;
+  const continues = (loopId: number | undefined): boolean =>
+    loopId === undefined
+      ? false
+      : callbacks.get(loopId)?.shouldContinue?.() !== false;
+  const machine = Machine.createTelegramMachineRunner<
+    TelegramTypingMachineState,
+    TelegramTypingEvent,
+    TelegramTypingEffect,
+    TelegramTypingStep
+  >({
+    initial: createTelegramTypingMachineState(),
+    transition: transitionTelegramTypingLoop,
+    run(effect) {
+      switch (effect.type) {
+        case "send": {
+          const send = callbacks.get(effect.loopId)?.sendTypingAction;
+          // Failures belong to the caller's action; the loop only needs to know the action is over.
+          void Promise.resolve()
+            .then(() => send?.(effect.chatId, effect.threadParams))
+            .then(
+              () => undefined,
+              () => undefined,
+            )
+            .then(() =>
+              machine.dispatch({ type: "sendSettled", sendId: effect.sendId }),
+            );
+          return;
+        }
+        case "armInterval":
+          interval = setInterval(
+            () =>
+              machine.dispatch({
+                type: "ticked",
+                continues: continues(machine.state.loop?.id),
+              }),
+            effect.intervalMs,
+          );
+          interval.unref?.();
+          return;
+        case "cancelInterval":
+          clearInterval(interval);
+          interval = undefined;
+          return;
+        case "loopEnded": {
+          const ended = callbacks.get(effect.loopId);
+          callbacks.delete(effect.loopId);
+          ended?.onStopped?.();
+          return;
+        }
+      }
+    },
+  });
+  return {
+    start(deps) {
+      const loopId = ++loopIds;
+      callbacks.set(loopId, deps);
+      const threadId = deps.target?.threadId;
+      const started = machine.dispatch({
+        type: "started",
+        loopId,
+        chatId: deps.chatId,
+        key: getTelegramTypingLoopKey(deps),
+        ...(Number.isInteger(threadId)
+          ? { threadParams: { message_thread_id: threadId! } }
+          : {}),
+        intervalMs: deps.intervalMs,
+        continues: continues(loopId),
+      });
+      if (machine.state.loop?.id !== loopId) callbacks.delete(loopId);
+      return started.result;
+    },
+    stop: () => machine.dispatch({ type: "stopRequested" }).result,
+    async waitForIdle(timeoutMs = TELEGRAM_TYPING_IDLE_DRAIN_MAX_MS) {
+      if (machine.state.inFlight === null) return;
+      const idle = machine.waitFor((state) => state.inFlight === null);
+      await Promise.race([
+        idle,
+        timeoutMs <= 0
+          ? Promise.resolve()
+          : new Promise<void>((resolve) => setTimeout(resolve, timeoutMs)),
+      ]);
+    },
+  };
 }
 
 export function createTelegramContextAbortHandlerSetter<
@@ -568,7 +724,7 @@ export interface TelegramPromptDispatchRuntime<TContext> {
     chatId?: number,
     options?: { target?: TelegramTypingLoopTarget },
   ) => boolean | void;
-  onPromptDispatchStart: (ctx: TContext, chatId?: number) => void;
+  onPromptDispatchStart: (ctx: TContext, chatId?: number, target?: TelegramTypingLoopTarget) => void;
   onPromptDispatchFailure: (ctx: TContext, message: string) => void;
 }
 
@@ -592,9 +748,9 @@ export function createTelegramPromptDispatchLifecycle<TContext>(
   deps: TelegramPromptDispatchLifecycleDeps<TContext>,
 ) {
   return {
-    onPromptDispatchStart: (ctx: TContext, chatId?: number): void => {
+    onPromptDispatchStart: (ctx: TContext, chatId?: number, target?: TelegramTypingLoopTarget): void => {
       deps.lifecycle.setDispatchPending(true);
-      deps.startTypingLoop(ctx, chatId);
+      deps.startTypingLoop(ctx, chatId, { target });
       updateTelegramRuntimeStatusSafely(deps.updateStatus, ctx, {
         category: "dispatch",
         phase: "status-update",

package/lib/sections.ts

@@ -289,8 +289,6 @@ export function getTelegramSectionDiagnostics(): TelegramSectionDiagnostic[] {
   return registry ? registry.getDiagnostics() : [];
 }
 
-// --- Registry ---
-
 const BACK_NAV_ROW = {
   text: "⬆️ Back",
 } as const;

package/lib/telegram-api.ts

@@ -540,7 +540,22 @@ function parseTelegramApiTargetInteger(value: unknown): number | undefined {
     : undefined;
 }
 
-export function createTelegramApiTargetActivityRuntime(): TelegramApiTargetActivityRuntime {
+/** Optional drain hints are not transport outcomes or request authority. */
+function captureApiDrainObserver(capture?: () => (() => void) | undefined): () => void {
+  try {
+    const notify = capture?.();
+    return () => {
+      try {
+        const emitted: unknown = notify?.();
+        if (emitted) void Promise.resolve(emitted).catch(() => undefined);
+      } catch { /* Observer failure is inert. */ }
+    };
+  } catch { return () => {}; }
+}
+
+export function createTelegramApiTargetActivityRuntime(deps: {
+  captureDrain?: () => (() => void) | undefined;
+} = {}): TelegramApiTargetActivityRuntime {
   const pending = new Map<
     string,
     {
@@ -580,18 +595,19 @@ export function createTelegramApiTargetActivityRuntime(): TelegramApiTargetActiv
       } else {
         pendingChats.set(chatId, (pendingChats.get(chatId) ?? 0) + 1);
       }
+      const notifyDrained = captureApiDrainObserver(deps.captureDrain);
       let completed = false;
       return () => {
         if (completed) return;
         completed = true;
         if (!key) {
           const count = pendingChats.get(chatId);
-          if (!count || count <= 1) pendingChats.delete(chatId);
+          if (!count || count <= 1) { pendingChats.delete(chatId); notifyDrained(); }
           else pendingChats.set(chatId, count - 1);
           return;
         }
         const current = pending.get(key);
-        if (!current || current.count <= 1) pending.delete(key);
+        if (!current || current.count <= 1) { pending.delete(key); notifyDrained(); }
         else current.count -= 1;
       };
     },
@@ -824,6 +840,11 @@ export interface TelegramBridgeApiRuntimeDeps {
   chatActionMaxGates?: number;
 }
 
+/** Typing issuance guard is local authority, never Bot API body or IPC data. */
+export interface TelegramTypingActionOptions extends Pick<TelegramApiCallOptions, "assertAuthority"> {
+  message_thread_id?: number;
+}
+
 export interface TelegramBridgeApiRuntime extends Pick<
   TelegramApiClient,
   "call" | "callMultipart"
@@ -849,7 +870,7 @@ export interface TelegramBridgeApiRuntime extends Pick<
   ) => Promise<boolean>;
   sendTypingAction: (
     chatId: number,
-    options?: { message_thread_id?: number },
+    options?: TelegramTypingActionOptions,
   ) => Promise<unknown>;
   sendRecordVoiceAction: (
     chatId: number,
@@ -1874,12 +1895,12 @@ export function createTelegramChatActionSender<TAction extends string>(
   sendChatAction: (
     chatId: number,
     action: TAction,
-    options?: { message_thread_id?: number },
+    options?: TelegramTypingActionOptions,
   ) => Promise<unknown>,
   action: TAction,
 ): (
   chatId: number,
-  options?: { message_thread_id?: number },
+  options?: TelegramTypingActionOptions,
 ) => Promise<unknown> {
   return (chatId, options) => sendChatAction(chatId, action, options);
 }
@@ -1958,6 +1979,7 @@ export type TelegramWorkspaceThreadDeletionTransport = (
 export function createDefaultTelegramBridgeApiRuntime(deps: {
   getBotToken: () => string | undefined;
   getBotScope?: () => string | undefined;
+  isThreadedMode?: () => boolean;
   recordRuntimeEvent: TelegramBridgeApiRuntimeDeps["recordRuntimeEvent"];
   captureRequestErrorHandler?: TelegramBridgeApiRuntimeDeps["captureRequestErrorHandler"];
   targetActivity?: TelegramApiTargetActivityRuntime;
@@ -1969,6 +1991,7 @@ export function createDefaultTelegramBridgeApiRuntime(deps: {
 } {
   const client = createTelegramApiClient(deps.getBotToken, {
     recordRuntimeEvent: deps.recordRuntimeEvent,
+    isThreadedMode: deps.isThreadedMode,
   });
   const admittedClient = deps.workspaceAdmission
     ? createTelegramApiWorkspaceAdmissionClient(
@@ -2114,6 +2137,8 @@ export function createTelegramBridgeApiRuntime(
         .then(() =>
           deps.client.call<TResponse>(method, body, {
             ...options,
+            // Presence is replaceable, not a queued body to replay after its session/loop owner ends.
+            ...(body.action === "typing" ? { maxAttempts: 1, retrySafety: "non-idempotent" as const } : {}),
             retryRateLimit: false,
           }),
         )
@@ -2270,7 +2295,7 @@ export function createTelegramBridgeApiRuntime(
           ...(options?.message_thread_id !== undefined
             ? { message_thread_id: options.message_thread_id }
             : {}),
-        }),
+        }, { assertAuthority: options?.assertAuthority }),
       "typing",
     ),
     sendRecordVoiceAction: createTelegramChatActionSender(
@@ -2405,10 +2430,34 @@ export function createTelegramBridgeApiRuntime(
  */
 export function createTelegramApiClient(
   getBotToken: () => string | undefined,
-  options: TelegramAnswerCallbackQueryOptions & { now?: () => number } = {},
+  options: TelegramAnswerCallbackQueryOptions & { now?: () => number; isThreadedMode?: () => boolean } = {},
 ): TelegramApiClient {
   const now = options.now ?? Date.now;
   const recordRuntimeEvent = options.recordRuntimeEvent;
+  const isThreadedMode = options.isThreadedMode;
+  const fenceOutput = (
+    method: string,
+    body: Record<string, unknown>,
+    callOptions?: TelegramApiCallOptions,
+  ): TelegramApiCallOptions | undefined => {
+    if (!isThreadedMode || !/^(send[A-Z]|copyMessages?$|forwardMessages?$)/.test(method)) return callOptions;
+    const assertAuthority = () => {
+      const chatId = typeof body.chat_id === "number" || typeof body.chat_id === "string"
+        ? Number(body.chat_id) : undefined;
+      const thread = body.message_thread_id;
+      const threadId = typeof thread === "number" || (typeof thread === "string" && /^[1-9][0-9]*$/.test(thread))
+        ? Number(thread) : undefined;
+      // Business connections and channels are distinct from the bot's private-chat All namespace.
+      if (
+        isThreadedMode() && chatId !== undefined && Number.isSafeInteger(chatId) && chatId > 0 &&
+        !(typeof body.business_connection_id === "string" && body.business_connection_id.length > 0) &&
+        (threadId === undefined || !Number.isSafeInteger(threadId) || threadId <= 0)
+      ) throw new Error("Telegram All is input-only in Threaded Mode; an explicit Thread target is required.");
+      callOptions?.assertAuthority?.();
+    };
+    assertAuthority();
+    return { ...callOptions, assertAuthority };
+  };
   const draftRetryNotBeforeByTarget = new Map<string, number>();
   return {
     call: async <TResponse>(
@@ -2416,6 +2465,8 @@ export function createTelegramApiClient(
       body: Record<string, unknown>,
       options?: TelegramApiCallOptions,
     ): Promise<TResponse> => {
+      body = { ...body };
+      options = fenceOutput(method, body, options);
       const token = getBotToken();
       // Cooldown keys retain only the public bot-id prefix, not the credential.
       const botId = token?.match(/^(\d+):/)?.[1];
@@ -2486,6 +2537,8 @@ export function createTelegramApiClient(
       fileName,
       options,
     ) => {
+      fields = { ...fields };
+      options = fenceOutput(method, fields, options);
       return callTelegramMultipart(
         getBotToken(),
         method,