@llblab/pi-telegram 0.18.4 → 0.18.6

package/lib/bus-transport.ts

@@ -0,0 +1,227 @@
+/**
+ * Telegram bus local transport boundary
+ * Zones: multi-instance bus, IPC transport, Windows named pipes, Unix sockets
+ * Owns endpoint derivation, transport-kind detection, retry/error classification, and small timing policy.
+ */
+
+import { createHash } from "node:crypto";
+import { createConnection } from "node:net";
+import { join, resolve } from "node:path";
+
+export type TelegramBusTransportKind = "pipe" | "socket";
+
+export type TelegramBusTransportEventRecorder = (
+  phase: string,
+  details: Record<string, unknown>,
+) => void;
+
+export type TelegramBusTransportEndpointDiagnostics = Record<
+  string,
+  unknown
+> & {
+  endpoint: string;
+  transport: TelegramBusTransportKind;
+};
+
+export interface TelegramBusTransportRetryPolicy {
+  attempts: number;
+  delayMs: number;
+}
+
+export interface TelegramBusTransportRetryPolicyOverrides {
+  attempts?: number;
+  delayMs?: number;
+}
+
+export type TelegramBusTransportOperation = "registration" | "operation";
+
+export const TELEGRAM_BUS_REGISTRATION_RETRY: TelegramBusTransportRetryPolicy = {
+  attempts: 10,
+  delayMs: 150,
+};
+
+export const TELEGRAM_BUS_OPERATION_RETRY: TelegramBusTransportRetryPolicy = {
+  attempts: 3,
+  delayMs: 100,
+};
+
+export const TELEGRAM_BUS_PIPE_REGISTRATION_RETRY =
+  TELEGRAM_BUS_REGISTRATION_RETRY;
+
+export const TELEGRAM_BUS_PIPE_OPERATION_RETRY = TELEGRAM_BUS_OPERATION_RETRY;
+
+export function getTelegramBusPipePath(input: {
+  agentDir: string;
+  scope: string;
+}): string {
+  const digest = createHash("sha256")
+    .update(resolve(input.agentDir))
+    .digest("base64url")
+    .slice(0, 16);
+  const scope = input.scope.replace(/[^a-zA-Z0-9_.-]/g, "_").slice(0, 80);
+  return `\\\\.\\pipe\\pi-telegram-${digest}-${scope}`;
+}
+
+export function isTelegramBusPipePath(endpoint: string): boolean {
+  return /^\\\\[.?]\\pipe\\/i.test(endpoint);
+}
+
+export function getTelegramBusTransportKind(
+  endpoint: string,
+): TelegramBusTransportKind {
+  return isTelegramBusPipePath(endpoint) ? "pipe" : "socket";
+}
+
+export function getTelegramBusEndpointDiagnostics(
+  endpoint: string,
+): TelegramBusTransportEndpointDiagnostics {
+  return {
+    endpoint,
+    transport: getTelegramBusTransportKind(endpoint),
+  };
+}
+
+export function getTelegramBusTransportRetryPolicy(input: {
+  endpoint: string;
+  operation: TelegramBusTransportOperation;
+  overrides?: TelegramBusTransportRetryPolicyOverrides;
+}): TelegramBusTransportRetryPolicy | undefined {
+  const base =
+    input.operation === "registration"
+      ? TELEGRAM_BUS_REGISTRATION_RETRY
+      : isTelegramBusPipePath(input.endpoint)
+        ? TELEGRAM_BUS_OPERATION_RETRY
+        : undefined;
+  if (!base && !input.overrides) return undefined;
+  return {
+    attempts: Math.max(1, input.overrides?.attempts ?? base?.attempts ?? 1),
+    delayMs: Math.max(0, input.overrides?.delayMs ?? base?.delayMs ?? 0),
+  };
+}
+
+export function getTelegramBusLeaderEndpoint(input: {
+  agentDir: string;
+  platform: NodeJS.Platform | string;
+}): string {
+  return input.platform === "win32"
+    ? getTelegramBusPipePath({ agentDir: input.agentDir, scope: "bus" })
+    : join(input.agentDir, "tmp", "telegram", "bus.sock");
+}
+
+export function getTelegramBusFollowerEndpoint(input: {
+  agentDir: string;
+  platform: NodeJS.Platform | string;
+  instanceId: string;
+}): string {
+  return input.platform === "win32"
+    ? getTelegramBusPipePath({
+        agentDir: input.agentDir,
+        scope: `follower-${input.instanceId}`,
+      })
+    : join(
+        input.agentDir,
+        "tmp",
+        "telegram",
+        "followers",
+        `${input.instanceId.replace(/[^a-zA-Z0-9_.-]/g, "_")}.sock`,
+      );
+}
+
+export interface TelegramBusTransportErrorInfo {
+  message: string;
+  code?: string;
+  syscall?: string;
+  kind: "connect" | "timeout" | "auth" | "protocol" | "unknown";
+  retryable: boolean;
+}
+
+export function classifyTelegramBusTransportError(
+  error: unknown,
+): TelegramBusTransportErrorInfo {
+  const message = error instanceof Error ? error.message : String(error);
+  const maybeNodeError = error as NodeJS.ErrnoException;
+  const code =
+    typeof maybeNodeError?.code === "string" ? maybeNodeError.code : undefined;
+  const syscall =
+    typeof maybeNodeError?.syscall === "string"
+      ? maybeNodeError.syscall
+      : undefined;
+  const timeout = code === "ETIMEDOUT" || /timed out/i.test(message);
+  const retryable =
+    code === "ENOENT" ||
+    code === "ECONNREFUSED" ||
+    code === "EPIPE" ||
+    code === "ECONNRESET" ||
+    code === "EBUSY" ||
+    timeout;
+  const kind = timeout
+    ? "timeout"
+    : code === "ENOENT" || code === "ECONNREFUSED"
+      ? "connect"
+      : "unknown";
+  return { message, code, syscall, kind, retryable };
+}
+
+export function isRetryableTelegramBusTransportError(error: unknown): boolean {
+  return classifyTelegramBusTransportError(error).retryable;
+}
+
+export function createTelegramBusTransportTimeoutError(
+  message: string,
+): NodeJS.ErrnoException {
+  const error = new Error(message) as NodeJS.ErrnoException;
+  error.code = "ETIMEDOUT";
+  return error;
+}
+
+export function delayTelegramBusTransportRetry(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    timer.unref?.();
+  });
+}
+
+export interface TelegramBusTransportProbeResult
+  extends TelegramBusTransportEndpointDiagnostics {
+  reachable: boolean;
+  error?: TelegramBusTransportErrorInfo;
+}
+
+export function probeTelegramBusEndpoint(input: {
+  endpoint: string;
+  timeoutMs?: number;
+}): Promise<TelegramBusTransportProbeResult> {
+  const timeoutMs = input.timeoutMs ?? 250;
+  const diagnostics = getTelegramBusEndpointDiagnostics(input.endpoint);
+  return new Promise((resolve) => {
+    const socket = createConnection(input.endpoint);
+    let settled = false;
+    const settle = (result: TelegramBusTransportProbeResult): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      socket.destroy();
+      resolve(result);
+    };
+    const timeout = setTimeout(() => {
+      settle({
+        ...diagnostics,
+        reachable: false,
+        error: classifyTelegramBusTransportError(
+          createTelegramBusTransportTimeoutError(
+            "Timed out probing Telegram bus endpoint",
+          ),
+        ),
+      });
+    }, timeoutMs);
+    timeout.unref?.();
+    socket.once("connect", () => settle({ ...diagnostics, reachable: true }));
+    socket.once("error", (error) =>
+      settle({
+        ...diagnostics,
+        reachable: false,
+        error: classifyTelegramBusTransportError(error),
+      }),
+    );
+  });
+}

package/lib/bus.ts

@@ -5,7 +5,7 @@
  * cross-instance forwarding helpers, and the live follower registry model.
  */
 
-import { createHash, randomBytes } from "node:crypto";
+import { randomBytes } from "node:crypto";
 import { chmodSync, existsSync, mkdirSync, unlinkSync } from "node:fs";
 import {
   createConnection,
@@ -16,6 +16,19 @@ import {
 import { homedir, platform as getPlatform } from "node:os";
 import { dirname, join, resolve } from "node:path";
 
+import {
+  classifyTelegramBusTransportError,
+  createTelegramBusTransportTimeoutError,
+  delayTelegramBusTransportRetry,
+  getTelegramBusEndpointDiagnostics,
+  getTelegramBusFollowerEndpoint,
+  getTelegramBusLeaderEndpoint,
+  getTelegramBusTransportRetryPolicy,
+  isTelegramBusPipePath,
+  isRetryableTelegramBusTransportError,
+  type TelegramBusTransportEventRecorder,
+  type TelegramBusTransportRetryPolicy,
+} from "./bus-transport.ts";
 import type { TelegramTarget } from "./target.ts";
 
 export type TelegramBusRole = "leader" | "follower";
@@ -30,30 +43,11 @@ export function createTelegramBusAuthSecret(): string {
   return randomBytes(32).toString("base64url");
 }
 
-function getTelegramBusPipePath(input: {
-  agentDir: string;
-  scope: string;
-}): string {
-  const digest = createHash("sha256")
-    .update(resolve(input.agentDir))
-    .digest("base64url")
-    .slice(0, 16);
-  const scope = input.scope.replace(/[^a-zA-Z0-9_.-]/g, "_").slice(0, 80);
-  return `\\\\.\\pipe\\pi-telegram-${digest}-${scope}`;
-}
-
-function isWindowsPipePath(socketPath: string): boolean {
-  return /^\\\\[.?]\\pipe\\/i.test(socketPath);
-}
-
 export function getTelegramBusSocketPath(
   agentDir = getAgentDir(),
   platform = getPlatform(),
 ): string {
-  if (platform === "win32") {
-    return getTelegramBusPipePath({ agentDir, scope: "bus" });
-  }
-  return join(agentDir, "tmp", "telegram", "bus.sock");
+  return getTelegramBusLeaderEndpoint({ agentDir, platform });
 }
 
 export function getTelegramBusFollowerSocketPath(
@@ -61,19 +55,7 @@ export function getTelegramBusFollowerSocketPath(
   agentDir = getAgentDir(),
   platform = getPlatform(),
 ): string {
-  if (platform === "win32") {
-    return getTelegramBusPipePath({
-      agentDir,
-      scope: `follower-${instanceId}`,
-    });
-  }
-  return join(
-    agentDir,
-    "tmp",
-    "telegram",
-    "followers",
-    `${instanceId.replace(/[^a-zA-Z0-9_.-]/g, "_")}.sock`,
-  );
+  return getTelegramBusFollowerEndpoint({ agentDir, platform, instanceId });
 }
 
 export interface TelegramBusInstanceRegistration {
@@ -91,6 +73,41 @@ export interface TelegramBusFollowerView extends TelegramBusInstanceRegistration
   lastHeartbeatMs: number;
 }
 
+export function getTelegramFollowerTargetOwnership(input: {
+  target: TelegramTarget;
+  followers: TelegramBusFollowerView[];
+  activeThreadRecords?: Array<{
+    status?: string;
+    instanceId?: string;
+    profileKey?: string;
+    owner?: { kind?: string };
+    target: TelegramTarget;
+  }>;
+  currentInstanceId?: string;
+}): { instanceId: string } | undefined {
+  const liveFollower = input.followers.find((follower) => {
+    return (
+      follower.target?.chatId === input.target.chatId &&
+      follower.target.threadId === input.target.threadId
+    );
+  });
+  if (liveFollower) return { instanceId: liveFollower.instanceId };
+  const record = input.activeThreadRecords?.find((candidate) => {
+    const isFollowerRecord = candidate.owner?.kind
+      ? candidate.owner.kind === "manual-follower"
+      : candidate.profileKey?.startsWith("manual:") === true;
+    return (
+      isFollowerRecord &&
+      candidate.status === "active" &&
+      candidate.instanceId &&
+      candidate.instanceId !== input.currentInstanceId &&
+      candidate.target.chatId === input.target.chatId &&
+      candidate.target.threadId === input.target.threadId
+    );
+  });
+  return record?.instanceId ? { instanceId: record.instanceId } : undefined;
+}
+
 export function isTelegramFollowerApiCallAllowed(input: {
   follower: TelegramBusFollowerView;
   method: string;
@@ -133,6 +150,28 @@ export function isTelegramFollowerApiCallAllowed(input: {
     const record = body as Record<string, unknown>;
     return matchesId(record.chat_id, target.chatId);
   };
+  const isTargetMessageScoped = (body: unknown): boolean => {
+    if (!isTargetChatScoped(body)) return false;
+    const messageId = (body as Record<string, unknown>).message_id;
+    const parsedMessageId =
+      typeof messageId === "number" ? messageId : Number(messageId);
+    return Number.isInteger(parsedMessageId) && matchesId(messageId, parsedMessageId);
+  };
+  const isBotCommandRegistration = (body: unknown): boolean => {
+    if (!body || typeof body !== "object" || Array.isArray(body)) return false;
+    const commands = (body as Record<string, unknown>).commands;
+    return (
+      Array.isArray(commands) &&
+      commands.every(
+        (command) =>
+          command &&
+          typeof command === "object" &&
+          !Array.isArray(command) &&
+          typeof (command as Record<string, unknown>).command === "string" &&
+          typeof (command as Record<string, unknown>).description === "string",
+      )
+    );
+  };
   if (input.method === "downloadFile") return true;
   if (input.method === "call") {
     const apiMethod = input.args[0];
@@ -144,7 +183,12 @@ export function isTelegramFollowerApiCallAllowed(input: {
       return true;
     }
     if (apiMethod === "getMe") return true;
+    if (apiMethod === "setMyCommands")
+      return isBotCommandRegistration(input.args[1]);
     if (apiMethod === "sendChatAction") return isTargetChatScoped(input.args[1]);
+    if (apiMethod === "deleteMessage" || apiMethod === "editMessageText") {
+      return isTargetMessageScoped(input.args[1]);
+    }
     return allowedCallMethods.has(apiMethod) && isTargetScoped(input.args[1]);
   }
   if (input.method === "callMultipart") {
@@ -310,12 +354,15 @@ export interface TelegramBusLocalServerDeps {
     | Promise<TelegramBusEnvelope | undefined>
     | TelegramBusEnvelope
     | undefined;
+  recordTransportEvent?: TelegramBusTransportEventRecorder;
 }
 
 export interface TelegramBusLocalClientOptions {
   socketPath: string;
   envelope: TelegramBusEnvelope;
   timeoutMs?: number;
+  retry?: TelegramBusTransportRetryPolicy;
+  recordTransportEvent?: TelegramBusTransportEventRecorder;
 }
 
 export interface TelegramBusForeignOwnedForwarderDeps {
@@ -362,6 +409,10 @@ export function createTelegramBusForeignOwnedUpdateForwarder<
       socketPath: deps.socketPath,
       envelope,
       timeoutMs: deps.timeoutMs,
+      retry: getTelegramBusTransportRetryPolicy({
+        endpoint: deps.socketPath,
+        operation: "operation",
+      }),
     });
     return response?.kind === "bus.ack" && response.ok;
   };
@@ -449,6 +500,10 @@ export function createTelegramBusFollowerTargetController(
         socketPath: follower.busSocketPath,
         envelope,
         timeoutMs: deps.timeoutMs,
+        retry: getTelegramBusTransportRetryPolicy({
+          endpoint: follower.busSocketPath,
+          operation: "operation",
+        }),
       });
       return response?.kind === "bus.ack" && response.ok;
     },
@@ -517,7 +572,11 @@ export function createTelegramBusLocalServer(
   return {
     start: async () => {
       if (server) return;
-      const usesWindowsPipe = isWindowsPipePath(deps.socketPath);
+      const usesWindowsPipe = isTelegramBusPipePath(deps.socketPath);
+      deps.recordTransportEvent?.(
+        "server-start",
+        getTelegramBusEndpointDiagnostics(deps.socketPath),
+      );
       if (!usesWindowsPipe) {
         const socketDir = dirname(deps.socketPath);
         mkdirSync(socketDir, { recursive: true, mode: 0o700 });
@@ -533,16 +592,40 @@ export function createTelegramBusLocalServer(
           const lines = buffer.split("\n");
           buffer = lines.pop() ?? "";
           for (const line of lines) {
-            void handleTelegramBusSocketLine(line, socket, deps.handleEnvelope);
+            void handleTelegramBusSocketLine(
+              line,
+              socket,
+              deps.handleEnvelope,
+              deps.recordTransportEvent,
+              deps.socketPath,
+            );
           }
         });
         socket.on("close", () => sockets.delete(socket));
-        socket.on("error", () => closeSocket(socket));
-      });
-      await new Promise<void>((resolve, reject) => {
-        server?.once("error", reject);
-        server?.listen(deps.socketPath, resolve);
+        socket.on("error", (error) => {
+          deps.recordTransportEvent?.("server-socket-error", {
+            ...getTelegramBusEndpointDiagnostics(deps.socketPath),
+            ...classifyTelegramBusTransportError(error),
+          });
+          closeSocket(socket);
+        });
       });
+      try {
+        await new Promise<void>((resolve, reject) => {
+          server?.once("error", reject);
+          server?.listen(deps.socketPath, resolve);
+        });
+        deps.recordTransportEvent?.(
+          "server-started",
+          getTelegramBusEndpointDiagnostics(deps.socketPath),
+        );
+      } catch (error) {
+        deps.recordTransportEvent?.("server-start-failed", {
+          ...getTelegramBusEndpointDiagnostics(deps.socketPath),
+          ...classifyTelegramBusTransportError(error),
+        });
+        throw error;
+      }
       if (!usesWindowsPipe) chmodSync(deps.socketPath, 0o600);
     },
     stop: async () => {
@@ -554,14 +637,27 @@ export function createTelegramBusLocalServer(
           activeServer.close(() => resolve()),
         );
       }
-      if (!isWindowsPipePath(deps.socketPath) && existsSync(deps.socketPath)) {
+      if (!isTelegramBusPipePath(deps.socketPath) && existsSync(deps.socketPath)) {
         unlinkSync(deps.socketPath);
       }
+      deps.recordTransportEvent?.(
+        "server-stopped",
+        getTelegramBusEndpointDiagnostics(deps.socketPath),
+      );
     },
   };
 }
 
-export function sendTelegramBusLocalEnvelope(
+function getTelegramBusEnvelopeDiagnostics(
+  envelope: TelegramBusEnvelope,
+): Record<string, unknown> {
+  return {
+    envelopeKind: envelope.kind,
+    requestId: envelope.requestId,
+  };
+}
+
+function sendTelegramBusLocalEnvelopeOnce(
   options: TelegramBusLocalClientOptions,
 ): Promise<TelegramBusEnvelope | undefined> {
   const timeoutMs = options.timeoutMs ?? 1000;
@@ -578,7 +674,11 @@ export function sendTelegramBusLocalEnvelope(
     };
     const timeout = setTimeout(() => {
       settle(() =>
-        reject(new Error("Timed out waiting for Telegram bus response")),
+        reject(
+          createTelegramBusTransportTimeoutError(
+            "Timed out waiting for Telegram bus response",
+          ),
+        ),
       );
     }, timeoutMs);
     timeout.unref?.();
@@ -598,6 +698,39 @@ export function sendTelegramBusLocalEnvelope(
   });
 }
 
+export async function sendTelegramBusLocalEnvelope(
+  options: TelegramBusLocalClientOptions,
+): Promise<TelegramBusEnvelope | undefined> {
+  const attempts = Math.max(1, options.retry?.attempts ?? 1);
+  const delayMs = Math.max(0, options.retry?.delayMs ?? 0);
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      return await sendTelegramBusLocalEnvelopeOnce(options);
+    } catch (error) {
+      const info = classifyTelegramBusTransportError(error);
+      options.recordTransportEvent?.("client-failed", {
+        ...getTelegramBusEndpointDiagnostics(options.socketPath),
+        ...getTelegramBusEnvelopeDiagnostics(options.envelope),
+        attempt,
+        attempts,
+        ...info,
+      });
+      if (attempt >= attempts || !isRetryableTelegramBusTransportError(error)) {
+        throw error;
+      }
+      options.recordTransportEvent?.("client-retry", {
+        ...getTelegramBusEndpointDiagnostics(options.socketPath),
+        ...getTelegramBusEnvelopeDiagnostics(options.envelope),
+        attempt,
+        attempts,
+        delayMs,
+        ...info,
+      });
+      await delayTelegramBusTransportRetry(delayMs);
+    }
+  }
+}
+
 export interface TelegramBusFollowerRegistry {
   register: (
     registration: TelegramBusInstanceRegistration,
@@ -610,6 +743,7 @@ export interface TelegramBusFollowerRegistry {
   getByTarget: (target: TelegramTarget) => TelegramBusFollowerView | undefined;
   list: () => TelegramBusFollowerView[];
   remove: (instanceId: string) => boolean;
+  clear: () => void;
   pruneStale: (
     nowMs: number,
     staleAfterMs: number,
@@ -627,6 +761,17 @@ export function createTelegramBusFollowerRegistry(): TelegramBusFollowerRegistry
   return {
     register: (registration) => {
       const existing = followers.get(registration.instanceId);
+      for (const [instanceId, follower] of followers.entries()) {
+        if (instanceId === registration.instanceId) continue;
+        const sameProfile =
+          registration.profileKey !== undefined &&
+          registration.profileKey === follower.profileKey;
+        const sameTarget =
+          registration.target !== undefined &&
+          follower.target?.chatId === registration.target.chatId &&
+          follower.target.threadId === registration.target.threadId;
+        if (sameProfile || sameTarget) followers.delete(instanceId);
+      }
       const next: TelegramBusFollowerView = {
         ...registration,
         target: registration.target ? { ...registration.target } : undefined,
@@ -660,6 +805,7 @@ export function createTelegramBusFollowerRegistry(): TelegramBusFollowerRegistry
     },
     list: () => [...followers.values()].map(clone),
     remove: (instanceId) => followers.delete(instanceId),
+    clear: () => followers.clear(),
     pruneStale: (nowMs, staleAfterMs) => {
       const removed: TelegramBusFollowerView[] = [];
       for (const [instanceId, follower] of followers.entries()) {
@@ -676,9 +822,15 @@ async function handleTelegramBusSocketLine(
   line: string,
   socket: Socket,
   handleEnvelope: TelegramBusLocalServerDeps["handleEnvelope"],
+  recordTransportEvent: TelegramBusTransportEventRecorder | undefined,
+  socketPath: string,
 ): Promise<void> {
   const envelope = parseTelegramBusEnvelope(line);
   if (!envelope) {
+    recordTransportEvent?.("server-invalid-envelope", {
+      ...getTelegramBusEndpointDiagnostics(socketPath),
+      byteLength: Buffer.byteLength(line),
+    });
     socket.write(
       encodeTelegramBusEnvelope({
         kind: "bus.ack",
@@ -689,8 +841,24 @@ async function handleTelegramBusSocketLine(
     );
     return;
   }
-  const response = await handleEnvelope(envelope);
-  if (response) socket.write(encodeTelegramBusEnvelope(response));
+  try {
+    const response = await handleEnvelope(envelope);
+    if (response) socket.write(encodeTelegramBusEnvelope(response));
+  } catch (error) {
+    recordTransportEvent?.("server-handler-failed", {
+      ...getTelegramBusEndpointDiagnostics(socketPath),
+      ...getTelegramBusEnvelopeDiagnostics(envelope),
+      ...classifyTelegramBusTransportError(error),
+    });
+    socket.write(
+      encodeTelegramBusEnvelope({
+        kind: "bus.ack",
+        requestId: envelope.requestId,
+        ok: false,
+        message: "Telegram bus handler failed.",
+      }),
+    );
+  }
 }
 
 function parseRegisterEnvelope(