@llblab/pi-telegram 0.20.0 → 0.20.2

package/lib/bus.ts

@@ -34,6 +34,40 @@ import { resolveAgentDir } from "./paths.ts";
 
 export type TelegramBusRole = "leader" | "follower";
 
+export interface TelegramBusProcessRuntime {
+  instanceId: string;
+  manualFollowerOwnerId: string;
+  getLeaderSocketPath: () => string;
+  getFollowerSocketPath: () => string;
+}
+
+export function createTelegramBusProcessRuntime(input: {
+  getActiveProfileName: () => string | undefined;
+  pid: number;
+  parentPid: number;
+  createdAtMs: number;
+}): TelegramBusProcessRuntime {
+  const instanceId = `${input.pid}:${input.createdAtMs}`;
+  const manualFollowerOwnerId = String(input.parentPid || input.pid);
+  return {
+    instanceId,
+    manualFollowerOwnerId,
+    getLeaderSocketPath: () =>
+      getTelegramBusSocketPath(
+        undefined,
+        undefined,
+        input.getActiveProfileName(),
+      ),
+    getFollowerSocketPath: () =>
+      getTelegramBusFollowerSocketPath(
+        instanceId,
+        undefined,
+        undefined,
+        input.getActiveProfileName(),
+      ),
+  };
+}
+
 export function createTelegramBusAuthSecret(): string {
   return randomBytes(32).toString("base64url");
 }
@@ -41,16 +75,23 @@ export function createTelegramBusAuthSecret(): string {
 export function getTelegramBusSocketPath(
   agentDir = resolveAgentDir(),
   platform = getPlatform(),
+  profileName?: string,
 ): string {
-  return getTelegramBusLeaderEndpoint({ agentDir, platform });
+  return getTelegramBusLeaderEndpoint({ agentDir, platform, profileName });
 }
 
 export function getTelegramBusFollowerSocketPath(
   instanceId: string,
   agentDir = resolveAgentDir(),
   platform = getPlatform(),
+  profileName?: string,
 ): string {
-  return getTelegramBusFollowerEndpoint({ agentDir, platform, instanceId });
+  return getTelegramBusFollowerEndpoint({
+    agentDir,
+    platform,
+    instanceId,
+    profileName,
+  });
 }
 
 export interface TelegramBusInstanceRegistration {
@@ -344,8 +385,16 @@ export interface TelegramBusLocalServer {
   stop: () => Promise<void>;
 }
 
+export type TelegramBusSocketPathSource = string | (() => string);
+
+export function resolveTelegramBusSocketPath(
+  source: TelegramBusSocketPathSource,
+): string {
+  return typeof source === "function" ? source() : source;
+}
+
 export interface TelegramBusLocalServerDeps {
-  socketPath: string;
+  socketPath: TelegramBusSocketPathSource;
   handleEnvelope: (
     envelope: TelegramBusEnvelope,
   ) =>
@@ -362,7 +411,7 @@ export interface TelegramBusLocalClientOptions {
 }
 
 export interface TelegramBusForeignOwnedForwarderDeps {
-  socketPath: string;
+  socketPath: TelegramBusSocketPathSource;
   createRequestId: () => string;
   getNowMs?: () => number;
   timeoutMs?: number;
@@ -401,12 +450,13 @@ export function createTelegramBusForeignOwnedUpdateForwarder<
   const getNowMs = deps.getNowMs ?? Date.now;
   const send = async (envelope: TelegramBusEnvelope): Promise<boolean> => {
     if (deps.getAuthSecret) envelope.auth = deps.getAuthSecret();
+    const socketPath = resolveTelegramBusSocketPath(deps.socketPath);
     const response = await sendTelegramBusLocalEnvelope({
-      socketPath: deps.socketPath,
+      socketPath,
       envelope,
       timeoutMs: deps.timeoutMs,
       retry: getTelegramBusTransportRetryPolicy({
-        endpoint: deps.socketPath,
+        endpoint: socketPath,
         operation: "operation",
       }),
     });
@@ -558,6 +608,7 @@ export function createTelegramBusLocalServer(
   deps: TelegramBusLocalServerDeps,
 ): TelegramBusLocalServer {
   let server: Server | undefined;
+  let activeSocketPath: string | undefined;
   const sockets = new Set<Socket>();
   const closeSocket = (socket: Socket) => {
     sockets.delete(socket);
@@ -566,16 +617,18 @@ export function createTelegramBusLocalServer(
   return {
     start: async () => {
       if (server) return;
-      const usesWindowsPipe = isTelegramBusPipePath(deps.socketPath);
+      const socketPath = resolveTelegramBusSocketPath(deps.socketPath);
+      activeSocketPath = socketPath;
+      const usesWindowsPipe = isTelegramBusPipePath(socketPath);
       deps.recordTransportEvent?.(
         "server-start",
-        getTelegramBusEndpointDiagnostics(deps.socketPath),
+        getTelegramBusEndpointDiagnostics(socketPath),
       );
       if (!usesWindowsPipe) {
-        const socketDir = dirname(deps.socketPath);
+        const socketDir = dirname(socketPath);
         mkdirSync(socketDir, { recursive: true, mode: 0o700 });
         chmodSync(socketDir, 0o700);
-        if (existsSync(deps.socketPath)) unlinkSync(deps.socketPath);
+        if (existsSync(socketPath)) unlinkSync(socketPath);
       }
       server = createServer((socket) => {
         sockets.add(socket);
@@ -591,14 +644,14 @@ export function createTelegramBusLocalServer(
               socket,
               deps.handleEnvelope,
               deps.recordTransportEvent,
-              deps.socketPath,
+              socketPath,
             );
           }
         });
         socket.on("close", () => sockets.delete(socket));
         socket.on("error", (error) => {
           deps.recordTransportEvent?.("server-socket-error", {
-            ...getTelegramBusEndpointDiagnostics(deps.socketPath),
+            ...getTelegramBusEndpointDiagnostics(socketPath),
             ...classifyTelegramBusTransportError(error),
           });
           closeSocket(socket);
@@ -607,24 +660,28 @@ export function createTelegramBusLocalServer(
       try {
         await new Promise<void>((resolve, reject) => {
           server?.once("error", reject);
-          server?.listen(deps.socketPath, resolve);
+          server?.listen(socketPath, resolve);
         });
         deps.recordTransportEvent?.(
           "server-started",
-          getTelegramBusEndpointDiagnostics(deps.socketPath),
+          getTelegramBusEndpointDiagnostics(socketPath),
         );
       } catch (error) {
+        server = undefined;
+        activeSocketPath = undefined;
         deps.recordTransportEvent?.("server-start-failed", {
-          ...getTelegramBusEndpointDiagnostics(deps.socketPath),
+          ...getTelegramBusEndpointDiagnostics(socketPath),
           ...classifyTelegramBusTransportError(error),
         });
         throw error;
       }
-      if (!usesWindowsPipe) chmodSync(deps.socketPath, 0o600);
+      if (!usesWindowsPipe) chmodSync(socketPath, 0o600);
     },
     stop: async () => {
       const activeServer = server;
+      const socketPath = activeSocketPath;
       server = undefined;
+      activeSocketPath = undefined;
       for (const socket of sockets) closeSocket(socket);
       if (activeServer) {
         await new Promise<void>((resolve) =>
@@ -632,15 +689,18 @@ export function createTelegramBusLocalServer(
         );
       }
       if (
-        !isTelegramBusPipePath(deps.socketPath) &&
-        existsSync(deps.socketPath)
+        socketPath &&
+        !isTelegramBusPipePath(socketPath) &&
+        existsSync(socketPath)
       ) {
-        unlinkSync(deps.socketPath);
+        unlinkSync(socketPath);
+      }
+      if (socketPath) {
+        deps.recordTransportEvent?.(
+          "server-stopped",
+          getTelegramBusEndpointDiagnostics(socketPath),
+        );
       }
-      deps.recordTransportEvent?.(
-        "server-stopped",
-        getTelegramBusEndpointDiagnostics(deps.socketPath),
-      );
     },
   };
 }

package/lib/paths.ts

@@ -71,6 +71,17 @@ export function resolveTelegramProfileTempFilePath(
   );
 }
 
+export function getTelegramDiagnosticsDisplayPaths(profileName?: string): {
+  state: string;
+  logs: string;
+} {
+  const suffix = getTelegramProfilePathSuffix(profileName);
+  return {
+    state: `~/.pi/agent/tmp/telegram/state${suffix}.json`,
+    logs: `~/.pi/agent/tmp/telegram/logs${suffix}.jsonl`,
+  };
+}
+
 /** Runtime event log (<agentDir>/tmp/telegram/logs.jsonl). */
 export function resolveTelegramRuntimeLogPath(): string {
   return resolveTelegramProfileTempFilePath("logs", "jsonl");

package/lib/prompts.ts

@@ -6,6 +6,7 @@
 
 import { Type } from "@sinclair/typebox";
 
+import { getTelegramDiagnosticsDisplayPaths } from "./paths.ts";
 import type { BeforeAgentStartEvent, ExtensionAPI } from "./pi.ts";
 import { TELEGRAM_PREFIX } from "./turns.ts";
 
@@ -17,7 +18,9 @@ const TELEGRAM_TURN_SYSTEM_PROMPT_SUFFIX = `
 
 Telegram turn note: If context was compacted or you need the pi-telegram bridge contract, call tool \`telegram_help\`; hidden comments are valid only for explicit \`telegram_voice\` or \`telegram_button\` actions with payload.`;
 
-const TELEGRAM_HELP_TEXT = `--- TELEGRAM BRIDGE HELP ---
+function buildTelegramHelpText(profileName?: string): string {
+  const diagnosticsPaths = getTelegramDiagnosticsDisplayPaths(profileName);
+  return `--- TELEGRAM BRIDGE HELP ---
 
 How to understand Telegram turns:
 - \`[telegram|thread:name|from:user|guest:group]\` marks Telegram origin and attributes.
@@ -60,15 +63,19 @@ Configurable handlers:
 - If command-template config is not enough, build a companion extension through the public pi-telegram APIs; do not import package-private \`lib/*\` paths.
 
 Debugging pi-telegram:
-- Inspect \`~/.pi/agent/tmp/telegram/state.json\` for runtime state, roster, bindings, slots, reservations, and diagnostics.
-- Inspect \`~/.pi/agent/tmp/telegram/logs.jsonl\` for redacted runtime event evidence.
+- Inspect \`${diagnosticsPaths.state}\` for runtime state, roster, bindings, slots, reservations, and diagnostics.
+- Inspect \`${diagnosticsPaths.logs}\` for redacted runtime event evidence.
 - Use terminal \`telegram-status\` for compact human health; use \`telegram-status --debug\` for the full human-readable diagnostic dump.`;
+}
 
-export function getTelegramHelpText(): string {
-  return TELEGRAM_HELP_TEXT;
+export function getTelegramHelpText(profileName?: string): string {
+  return buildTelegramHelpText(profileName);
 }
 
-export function registerTelegramHelpTool(pi: ExtensionAPI): void {
+export function registerTelegramHelpTool(
+  pi: ExtensionAPI,
+  options: { getActiveProfileName?: () => string | undefined } = {},
+): void {
   pi.registerTool({
     name: "telegram_help",
     label: "Telegram Help",
@@ -77,7 +84,12 @@ export function registerTelegramHelpTool(pi: ExtensionAPI): void {
     parameters: Type.Object({}),
     async execute() {
       return {
-        content: [{ type: "text", text: getTelegramHelpText() }],
+        content: [
+          {
+            type: "text",
+            text: getTelegramHelpText(options.getActiveProfileName?.()),
+          },
+        ],
         details: {},
       };
     },

package/lib/setup.ts

@@ -27,6 +27,11 @@ export interface TelegramPollingStartResult {
   message?: string;
 }
 
+export type TelegramSetupCompletion =
+  | { status: "success"; config: TelegramSetupConfig }
+  | { status: "cancelled" | "unavailable" | "busy" | "validation-failed" }
+  | { status: "polling-failed"; config: TelegramSetupConfig };
+
 export interface TelegramSetupDeps {
   hasUI: boolean;
   env: NodeJS.ProcessEnv;
@@ -120,8 +125,8 @@ export function getTelegramBotTokenPromptSpec(
 
 export async function runTelegramSetup(
   deps: TelegramSetupDeps,
-): Promise<TelegramSetupConfig | undefined> {
-  if (!deps.hasUI) return undefined;
+): Promise<TelegramSetupCompletion> {
+  if (!deps.hasUI) return { status: "unavailable" };
   const tokenPrompt = getTelegramBotTokenPromptSpec(
     deps.env,
     deps.config.botToken,
@@ -130,7 +135,7 @@ export async function runTelegramSetup(
     tokenPrompt.method === "editor"
       ? await deps.promptEditor("Telegram bot token", tokenPrompt.value)
       : await deps.promptInput("Telegram bot token", tokenPrompt.value);
-  if (!token) return undefined;
+  if (!token) return { status: "cancelled" };
   const nextConfig: TelegramSetupConfig = {
     ...deps.config,
     botToken: token.trim(),
@@ -141,11 +146,11 @@ export async function runTelegramSetup(
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     deps.notify(`Telegram API check failed: ${message}`, "error");
-    return undefined;
+    return { status: "validation-failed" };
   }
   if (!data.ok || !data.result) {
     deps.notify(data.description || "Invalid Telegram bot token", "error");
-    return undefined;
+    return { status: "validation-failed" };
   }
   nextConfig.botId = data.result.id;
   nextConfig.botUsername = data.result.username;
@@ -158,21 +163,33 @@ export async function runTelegramSetup(
     "Send /start to your bot in Telegram to pair this extension with your account.",
     "info",
   );
-  const startResult = await deps.startPolling();
+  let startResult: unknown;
+  try {
+    startResult = await deps.startPolling();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    deps.notify(`Telegram polling failed: ${message}`, "error");
+    deps.updateStatus();
+    return { status: "polling-failed", config: nextConfig };
+  }
   if (isTelegramPollingStartResult(startResult) && startResult.message) {
     deps.notify(startResult.message, startResult.ok ? "info" : "error");
   }
   deps.updateStatus();
-  return nextConfig;
+  if (isTelegramPollingStartResult(startResult) && !startResult.ok) {
+    return { status: "polling-failed", config: nextConfig };
+  }
+  return { status: "success", config: nextConfig };
 }
 
 export function createTelegramSetupPromptRuntime<
   TContext extends TelegramSetupPromptContext,
 >(deps: TelegramSetupPromptRuntimeDeps<TContext>) {
-  return async (ctx: TContext): Promise<void> => {
-    if (!ctx.hasUI || !deps.setupGuard.start()) return;
+  return async (ctx: TContext): Promise<TelegramSetupCompletion> => {
+    if (!ctx.hasUI) return { status: "unavailable" };
+    if (!deps.setupGuard.start()) return { status: "busy" };
     try {
-      await runTelegramSetup({
+      return await runTelegramSetup({
         hasUI: ctx.hasUI,
         env: deps.env ?? process.env,
         config: deps.getConfig(),

package/lib/status.ts

@@ -1065,6 +1065,13 @@ function buildTelegramBridgeCompactStatusLines(
       : state.activeSourceMessageIds?.length
         ? "active"
         : "idle";
+  const profileSuffix = state.activeProfileName
+    ? `.${state.activeProfileName.replace(/[^a-zA-Z0-9._-]+/g, "_")}`
+    : "";
+  const diagnosticsPaths = {
+    state: `~/.pi/agent/tmp/telegram/state${profileSuffix}.json`,
+    logs: `~/.pi/agent/tmp/telegram/logs${profileSuffix}.jsonl`,
+  };
   return [
     "connection:",
     `- bot: ${formatTelegramBridgeBotStatus(state)}`,
@@ -1094,8 +1101,8 @@ function buildTelegramBridgeCompactStatusLines(
     ...buildTelegramThreadReconciliationLines(state),
     "",
     "diagnostics:",
-    "- state: ~/.pi/agent/tmp/telegram/state.json",
-    "- logs: ~/.pi/agent/tmp/telegram/logs.jsonl",
+    `- state: ${diagnosticsPaths.state}`,
+    `- logs: ${diagnosticsPaths.logs}`,
     "- full dump: /telegram-status --debug",
   ];
 }

package/lib/threads.ts

@@ -133,30 +133,32 @@ function getNextMonotonicSlot(
   nowMs: number,
   lastSlot?: string,
 ): string | undefined {
-  let maxCode = "A".charCodeAt(0) - 1;
-  for (const record of records.values()) {
-    if (!record.slot || !isCurrentThreadRecord(record)) continue;
-    maxCode = Math.max(maxCode, record.slot.charCodeAt(0));
-  }
-  for (const reservation of reservations) {
-    if (
-      reservation.expiresAtMs !== undefined &&
-      reservation.expiresAtMs <= nowMs
-    )
-      continue;
-    if (!reservation.slot) continue;
-    maxCode = Math.max(maxCode, reservation.slot.charCodeAt(0));
-  }
-  for (const provision of pendingProvisions) {
-    if (provision.expiresAtMs !== undefined && provision.expiresAtMs <= nowMs)
-      continue;
-    if (!provision.slot) continue;
-    maxCode = Math.max(maxCode, provision.slot.charCodeAt(0));
-  }
+  let cursorCode: number | undefined;
   if (lastSlot && /^[A-Z]$/.test(lastSlot)) {
-    maxCode = Math.max(maxCode, lastSlot.charCodeAt(0));
+    cursorCode = lastSlot.charCodeAt(0);
+  } else {
+    cursorCode = "A".charCodeAt(0) - 1;
+    for (const record of records.values()) {
+      if (!record.slot || !isCurrentThreadRecord(record)) continue;
+      cursorCode = Math.max(cursorCode, record.slot.charCodeAt(0));
+    }
+    for (const reservation of reservations) {
+      if (
+        reservation.expiresAtMs !== undefined &&
+        reservation.expiresAtMs <= nowMs
+      )
+        continue;
+      if (!reservation.slot) continue;
+      cursorCode = Math.max(cursorCode, reservation.slot.charCodeAt(0));
+    }
+    for (const provision of pendingProvisions) {
+      if (provision.expiresAtMs !== undefined && provision.expiresAtMs <= nowMs)
+        continue;
+      if (!provision.slot) continue;
+      cursorCode = Math.max(cursorCode, provision.slot.charCodeAt(0));
+    }
   }
-  let code = maxCode + 1;
+  let code = cursorCode + 1;
   if (code > "Z".charCodeAt(0)) code = "A".charCodeAt(0);
   for (let attempt = 0; attempt < 26; attempt++) {
     const candidate = String.fromCharCode(code);
@@ -228,6 +230,39 @@ export interface TelegramTopicTargetStore {
   ) => TelegramTopicTargetRecord | undefined;
 }
 
+export function reconcileTelegramFreshAllocationCursor(
+  store: Pick<
+    TelegramTopicTargetStore,
+    "getBotState" | "list" | "setBotState"
+  >,
+  nowMs = Date.now(),
+): boolean {
+  const currentCursor = store.getBotState().lastSlot;
+  const slottedRecords = store
+    .list()
+    .filter((record) => !!record.slot && /^[A-Z]$/.test(record.slot));
+  if (slottedRecords.some((record) => record.slot === currentCursor)) {
+    return false;
+  }
+  const latestLiveRecord = slottedRecords.reduce<
+    TelegramTopicTargetRecord | undefined
+  >((latest, record) => {
+    if (!latest) return record;
+    if (record.createdAtMs !== latest.createdAtMs) {
+      return record.createdAtMs > latest.createdAtMs ? record : latest;
+    }
+    return record.updatedAtMs > latest.updatedAtMs ? record : latest;
+  }, undefined);
+  const nextCursor = latestLiveRecord?.slot;
+  if (nextCursor === currentCursor) return false;
+  store.setBotState({
+    lastSlot: nextCursor,
+    updatedAtMs: nowMs,
+    lastReconcileAction: "live-cursor-realignment",
+  });
+  return true;
+}
+
 export interface TelegramTopicTargetStoreOptions {
   path: string | (() => string);
   getNowMs?: () => number;
@@ -881,9 +916,6 @@ export function createTelegramTopicTargetStore(
 
   const rememberSlot = (slot: string | undefined, nowMs = getNowMs()) => {
     if (!slot || !/^[A-Z]$/.test(slot)) return;
-    const currentCode =
-      botState.lastSlot?.charCodeAt(0) ?? "A".charCodeAt(0) - 1;
-    if (slot.charCodeAt(0) < currentCode) return;
     botState = { ...botState, lastSlot: slot, updatedAtMs: nowMs };
   };
   const rememberIdentity = (record: TelegramTopicTargetRecord) => {
@@ -1151,6 +1183,7 @@ export function createTelegramTopicTargetStore(
     upsert(record) {
       const next = cloneRecord(record);
       const nextOwnerKey = getRecordOwnerKey(next);
+      const previousRecord = records.get(nextOwnerKey);
       if (isCurrentThreadRecord(next)) {
         for (const existing of Array.from(records.values())) {
           const existingOwnerKey = getRecordOwnerKey(existing);
@@ -1180,7 +1213,12 @@ export function createTelegramTopicTargetStore(
         return cloneRecord(next);
       }
       records.set(nextOwnerKey, next);
-      rememberSlot(next.slot, next.updatedAtMs);
+      if (
+        !previousRecord ||
+        !targetMatches(previousRecord.target, next.target)
+      ) {
+        rememberSlot(next.slot, next.updatedAtMs);
+      }
       rememberIdentity(next);
       loaded = true;
       dirty = true;

package/lib/turns.ts

@@ -8,8 +8,6 @@ import { readFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
 
 import {
-  appendTelegramForwardContext,
-  appendTelegramReplyContext,
   buildTelegramReplyContextBlock,
   collectTelegramMessageIds,
   downloadTelegramMessageFiles,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.20.0",
+  "version": "0.20.2",
   "private": false,
   "publishConfig": {
     "access": "public"