@llblab/pi-kit 0.36.1 → 0.36.3

package/node_modules/@llblab/pi-telegram/lib/bus-follower.ts

@@ -70,6 +70,7 @@ import {
   type TelegramBusSelectedMenuTextEffect,
   type TelegramBusSocketPathSource,
   type TelegramBusWorkspaceRestoreObservation,
+  TELEGRAM_BUS_FOLLOWER_API_NOT_ALLOWED_MESSAGE,
 } from "./bus.ts";
 import type {
   TelegramConfigStore,
@@ -96,6 +97,7 @@ import {
   assertTelegramApiCallAuthority,
   TelegramApiAuthorityError,
   TelegramApiCommitUnknownError,
+  TelegramApiFollowerNotAllowedError,
   TelegramApiStaleTargetError,
   type TelegramApiCallOptions,
 } from "./telegram-api.ts";
@@ -1917,11 +1919,16 @@ export function createTelegramBusFollowerApiCaller(
     method: string,
     args: unknown[],
     localOptions: Pick<TelegramApiCallOptions, "assertAuthority"> | undefined,
-    timing: { registeredAtMs?: number },
+    timing: { registeredAtMs?: number; apiMethod?: string },
   ): Promise<unknown> => {
     const assertion = localOptions?.assertAuthority;
     const assertCurrent = () => assertTelegramApiCallAuthority(assertion, false);
     assertCurrent();
+    // Match IPC's JSON semantics once, before awaits; send and refusal metadata share this identity.
+    const requestArgs = JSON.parse(JSON.stringify(args)) as unknown[];
+    const apiMethod = (method === "call" || method === "callMultipart") && typeof requestArgs[0] === "string"
+      ? requestArgs[0] : method;
+    timing.apiMethod = apiMethod;
     const registration = await resolveTelegramBusFollowerRegistration(
       deps,
       timeoutMs,
@@ -1941,18 +1948,13 @@ export function createTelegramBusFollowerApiCaller(
           instanceId: deps.instanceId,
           registrationGeneration: registration.generation,
           method,
-          args,
+          args: requestArgs,
           sentAtMs: getNowMs(),
         },
         assertion ? assertCurrent : undefined,
       );
     } catch (error) {
       if (error instanceof TelegramBusLocalAuthorityError) throw new TelegramApiAuthorityError(error.requestIssued);
-      const apiMethod =
-        (method === "call" || method === "callMultipart") &&
-        typeof args[0] === "string"
-          ? args[0]
-          : method;
       if (!isTelegramApiMethodRetrySafe(apiMethod)) {
         throw new TelegramApiCommitUnknownError(apiMethod, error);
       }
@@ -1986,11 +1988,30 @@ export function createTelegramBusFollowerApiCaller(
         new Error(message ?? "Telegram bus API call result is ambiguous."),
       );
     }
+    const refusedMethod = response?.kind === "bus.ack" && !response.ok &&
+      response.error?.code === "follower-api-not-allowed" &&
+      response.error.method === apiMethod
+      ? apiMethod : undefined;
+    if (refusedMethod || message === TELEGRAM_BUS_FOLLOWER_API_NOT_ALLOWED_MESSAGE) {
+      const body =
+        (method === "call" || method === "callMultipart") && isRecord(requestArgs[1])
+          ? requestArgs[1]
+          : undefined;
+      const chatId = Number(body?.chat_id);
+      const threadId = Number(body?.message_thread_id);
+      throw new TelegramApiFollowerNotAllowedError(
+        message ?? TELEGRAM_BUS_FOLLOWER_API_NOT_ALLOWED_MESSAGE,
+        Number.isSafeInteger(chatId) && Number.isSafeInteger(threadId)
+          ? { chatId, threadId }
+          : undefined,
+        refusedMethod,
+      );
+    }
     throw new Error(message ?? "Telegram bus API call failed.");
   };
   return async (method, args, localOptions) => {
     const startedAtMs = getNowMs();
-    const timing: { registeredAtMs?: number } = {};
+    const timing: { registeredAtMs?: number; apiMethod?: string } = {};
     let outcome = "ok";
     try {
       return await caller(method, args, localOptions, timing);
@@ -2000,11 +2021,7 @@ export function createTelegramBusFollowerApiCaller(
     } finally {
       const elapsedMs = getNowMs() - startedAtMs;
       if (elapsedMs >= slowCallMs) {
-        const apiMethod =
-          (method === "call" || method === "callMultipart") &&
-          typeof args[0] === "string"
-            ? args[0]
-            : method;
+        const apiMethod = timing.apiMethod ?? method;
         try {
           deps.recordRuntimeEvent?.(
             "bus",

package/node_modules/@llblab/pi-telegram/lib/bus-leader.ts

@@ -40,6 +40,7 @@ import {
   type TelegramBusProtocolIdentity,
   type TelegramBusSelectedMenuDelivery,
   type TelegramBusSocketPathSource,
+  TELEGRAM_BUS_FOLLOWER_API_NOT_ALLOWED_MESSAGE,
 } from "./bus.ts";
 import type { TelegramThreadDisplayMode } from "./config.ts";
 import type { TelegramAttachmentSource } from "./media.ts";
@@ -464,6 +465,9 @@ export function createTelegramBusLeaderRuntimeAssembly<TContext>(
           store: deps.topicTargetStore,
           getLeaderEpoch: deps.getCurrentLeaderEpoch,
           getExternalProtection: deps.captureWorkspaceExternalProtection,
+          onSlotReused: (bindingKey, isCurrent) => display
+            ? reconcileThreadDisplay(bindingKey, isCurrent).then(() => undefined)
+            : Promise.resolve(),
           recordEvent(message, details) {
             deps.recordRuntimeEvent("bus", message, details);
           },
@@ -513,6 +517,9 @@ export function createTelegramBusLeaderRuntimeAssembly<TContext>(
         getLeaderEpoch: () => deps.getCurrentLeaderEpoch?.(),
         captureLiveBindingKeys,
         captureBindingAuthority(binding) {
+          // Slotless retained bindings need display repair even without a live owner.
+          // The reconciler still fences the exact binding snapshot, profile, mode and epoch.
+          if (binding.slot === undefined) return () => true;
           const matches = (target: TelegramTarget | undefined) =>
             target?.chatId === binding.target.chatId &&
             target?.threadId === binding.target.threadId;
@@ -544,19 +551,22 @@ export function createTelegramBusLeaderRuntimeAssembly<TContext>(
         callApi: deps.callApi,
       })
     : undefined;
-  const reconcileThreadDisplayOperation = async () => {
-    const result = await display!.reconcile();
+  const reconcileThreadDisplayOperation = async (bindingKey?: string) => {
+    const result = await display!.reconcile(bindingKey);
     deps.onThreadDisplayChanged?.();
     return result;
   };
-  const reconcileThreadDisplay = () =>
+  const reconcileThreadDisplay = (bindingKey?: string, isCurrent: () => boolean = () => true) =>
     runWorkspaceOperation(
       {
         operationId: createTelegramWorkspaceAdmissionOperationId(),
         operationKind: "workspace.reconcile-display",
         scopes: [{ kind: "profile" }],
       },
-      reconcileThreadDisplayOperation,
+      () => {
+        if (!isCurrent()) throw new Error("Telegram Thread display update lost allocation authority.");
+        return reconcileThreadDisplayOperation(bindingKey);
+      },
     );
   let startupDisplayTimer: ReturnType<typeof setTimeout> | undefined;
   let startupDisplayGeneration = 0;
@@ -4179,10 +4189,17 @@ async function handleFollowerApiCall(
       args: envelope.args,
     })
   ) {
-    return rejectTelegramBusRequest(
-      envelope.requestId,
-      "Telegram bus API call is not allowed for this follower.",
-    );
+    const apiMethod = getFollowerApiMethodAndBody(envelope).apiMethod;
+    return {
+      ...rejectTelegramBusRequest(
+        envelope.requestId,
+        TELEGRAM_BUS_FOLLOWER_API_NOT_ALLOWED_MESSAGE,
+      ),
+      // Only this pre-dispatch authorizer refusal certifies that the API method was not called.
+      ...(/^[A-Za-z][A-Za-z0-9]{0,63}$/.test(apiMethod)
+        ? { error: { code: "follower-api-not-allowed" as const, method: apiMethod } }
+        : {}),
+    };
   }
   if (!deps.callApi) {
     return rejectTelegramBusRequest(

package/node_modules/@llblab/pi-telegram/lib/bus.ts

@@ -1260,6 +1260,7 @@ export type TelegramBusEnvelope = (
           | "ledger-overloaded"
           | "incompatible-protocol"
           | "stale-target"
+          | "follower-api-not-allowed"
           | "workspace-binding-unavailable";
         method?: string;
         chatId?: number;
@@ -2873,6 +2874,9 @@ export function isTelegramBusEnvelopeAuthorized(
 }
 
 /** Negative acknowledgement carrying only a diagnostic message. */
+export const TELEGRAM_BUS_FOLLOWER_API_NOT_ALLOWED_MESSAGE =
+  "Telegram bus API call is not allowed for this follower.";
+
 export function rejectTelegramBusRequest(
   requestId: string,
   message: string,
@@ -4145,10 +4149,17 @@ function parseAckEnvelope(
       code === "ledger-overloaded" ||
       code === "incompatible-protocol" ||
       code === "stale-target" ||
+      code === "follower-api-not-allowed" ||
       code === "workspace-binding-unavailable"
     ) {
       const chatId = value.error.chatId;
       const threadId = value.error.threadId;
+      if (
+        code === "follower-api-not-allowed" &&
+        (value.ok || Object.hasOwn(value, "result") ||
+          typeof value.error.method !== "string" ||
+          !/^[A-Za-z][A-Za-z0-9]{0,63}$/.test(value.error.method))
+      ) return undefined;
       if (
         code === "stale-target" &&
         (!Number.isSafeInteger(chatId) || !Number.isSafeInteger(threadId))

package/node_modules/@llblab/pi-telegram/lib/commands.ts

@@ -36,6 +36,7 @@ import {
   TelegramApiAuthorityError,
   type TelegramApiCallOptions,
 } from "./telegram-api.ts";
+import type { TelegramTarget } from "./target.ts";
 import type { TelegramSessionReplacementIntent } from "./threads.ts";
 import {
   acquireTelegramUpdateRouting,
@@ -1194,34 +1195,38 @@ export interface TelegramCommandTargetRuntimeDeps<TContext> {
   ) => void;
   getAdmissionScope?: () => string | undefined;
   getAdmissionJournalBinding?: () => string | undefined;
+  /** Ordinary reply destination selected before publication, not resend authority. */
+  getReplyTarget?: (
+    message: TelegramCommandRuntimeMessage,
+  ) => TelegramTarget | undefined;
   onControlQueued?: (
     message: TelegramCommandRuntimeMessage,
     receipt: TelegramQueueAdmissionReceipt,
   ) => void;
   showStatus: (
     chatId: number,
-    replyToMessageId: number,
+    replyToMessageId: number | undefined,
     ctx: TContext,
     threadId?: number,
     options?: Pick<TelegramApiCallOptions, "assertAuthority">,
   ) => Promise<void>;
   openModelMenu: (
     chatId: number,
-    replyToMessageId: number,
+    replyToMessageId: number | undefined,
     ctx: TContext,
     threadId?: number,
     options?: Pick<TelegramApiCallOptions, "assertAuthority">,
   ) => Promise<void>;
   openSettingsMenu?: (
     chatId: number,
-    replyToMessageId: number,
+    replyToMessageId: number | undefined,
     ctx: TContext,
     threadId?: number,
     options?: Pick<TelegramApiCallOptions, "assertAuthority">,
   ) => Promise<void>;
   sendTextReply: (
     chatId: number,
-    replyToMessageId: number,
+    replyToMessageId: number | undefined,
     text: string,
     options?: {
       parseMode?: "HTML";
@@ -1336,6 +1341,7 @@ export function createTelegramCommandTargetQueueRuntime<
       createControlItem,
       enqueueControlItem: controlQueueController.enqueue,
     }),
+    getReplyTarget: deps.getReplyTarget,
     getAdmissionScope: deps.getAdmissionScope,
     getAdmissionJournalBinding: deps.getAdmissionJournalBinding,
     onControlQueued: deps.onControlQueued,
@@ -1352,6 +1358,25 @@ export function createTelegramCommandTargetRuntime<
 >(
   deps: TelegramCommandTargetRuntimeDeps<TContext>,
 ): TelegramCommandTargetRuntime<TMessage, TContext> {
+  const getReplyTarget = (
+    message: TMessage,
+    options?: Pick<TelegramApiCallOptions, "assertAuthority">,
+  ) => {
+    const source = getTelegramCommandMessageTarget(message);
+    const recipient = options?.assertAuthority
+      ? undefined
+      : deps.getReplyTarget?.(message);
+    if (!recipient) return source;
+    if (recipient.chatId !== source.chatId)
+      throw new Error("Telegram command reply cannot change its recipient chat.");
+    if (source.threadId !== undefined && recipient.threadId === undefined)
+      throw new Error("Telegram command cannot move a Thread reply to All.");
+    return {
+      ...recipient,
+      replyToMessageId:
+        recipient.threadId === source.threadId ? source.replyToMessageId : undefined,
+    };
+  };
   return {
     enqueueControlItem: (message, ctx, controlType, statusSummary, execute) => {
       const sourceUpdateId = message.pi_telegram_source_update_id;
@@ -1381,7 +1406,7 @@ export function createTelegramCommandTargetRuntime<
       );
     },
     showStatus: (message, ctx, options) => {
-      const target = getTelegramCommandMessageTarget(message);
+      const target = getReplyTarget(message, options);
       return deps.showStatus(
         target.chatId,
         target.replyToMessageId,
@@ -1391,7 +1416,7 @@ export function createTelegramCommandTargetRuntime<
       );
     },
     openModelMenu: (message, ctx, options) => {
-      const target = getTelegramCommandMessageTarget(message);
+      const target = getReplyTarget(message, options);
       return deps.openModelMenu(
         target.chatId,
         target.replyToMessageId,
@@ -1401,7 +1426,7 @@ export function createTelegramCommandTargetRuntime<
       );
     },
     openSettingsMenu: async (message, ctx, options) => {
-      const target = getTelegramCommandMessageTarget(message);
+      const target = getReplyTarget(message, options);
       if (!deps.openSettingsMenu) {
         await deps.sendTextReply(
           target.chatId,
@@ -1423,7 +1448,7 @@ export function createTelegramCommandTargetRuntime<
       );
     },
     sendTextReply: async (message, text, options) => {
-      const target = getTelegramCommandMessageTarget(message);
+      const target = getReplyTarget(message, options);
       const assertAuthority = options?.assertAuthority,
         send = deps.sendTextReply;
       const capturedOptions = { ...options, target };
@@ -2217,6 +2242,7 @@ export function createTelegramCommandHandlerTargetRuntime<
     }),
     appendControlItem: deps.appendControlItem,
     dispatchNextQueuedTelegramTurn: deps.dispatchNextQueuedTelegramTurn,
+    getReplyTarget: deps.getReplyTarget,
     getAdmissionScope: deps.getAdmissionScope,
     getAdmissionJournalBinding: deps.getAdmissionJournalBinding,
     onControlQueued: deps.onControlQueued,

package/node_modules/@llblab/pi-telegram/lib/extension.ts

@@ -590,18 +590,32 @@ export default function (pi: Pi.ExtensionAPI) {
         );
       },
     });
-  const inactiveThreadCleanupReviewRuntime =
-    ThreadCleanupManager.createTelegramInactiveThreadCleanupReviewRuntime({
-      getProfileName() {
-        return configStore.getActiveProfileName() ?? "default";
+  const inactiveThreadCleanupRuntime =
+    ThreadCleanupManager.createTelegramInactiveThreadCleanupRuntime({
+      store: threadStore,
+      captureAuthority() {
+        const ledger = workspaceAdmissionRuntime.resolve();
+        const leaderEpoch = getCurrentLeaderEpoch();
+        const operator = configStore.getAllowedUserId();
+        if (!ledger || leaderEpoch === undefined || operator === undefined) return undefined;
+        const stamp = telegramTransportStampRuntime.getStamp();
+        const generation = telegramSessionContextStore.getGeneration();
+        return {
+          profileName: configStore.getActiveProfileName() ?? "default",
+          leaderEpoch, ledger,
+          isCurrent() {
+            return getCurrentLeaderEpoch() === leaderEpoch &&
+              telegramTransportStampRuntime.isActive(stamp) &&
+              configStore.getAllowedUserId() === operator &&
+              telegramSessionContextStore.getGeneration() === generation;
+          },
+        };
       },
-      listBindings: threadStore.listWorkspaceBindings,
       getProtection: captureWorkspaceExternalProtection,
-      listReservations: threadStore.listReservations,
-      listPendingProvisions: threadStore.listPendingProvisions,
-      listPendingCleanups: threadStore.listPendingCleanups,
-      getWorkStore() {
-        const profileName = configStore.getActiveProfileName() ?? "default";
+      getProcessLiveness: ProcessIdentity.getTelegramProcessLiveness,
+      runExclusive: telegramWorkspaceOperationRuntime.runExclusive,
+      getWorkStore(authority) {
+        const profileName = authority.profileName;
         const botToken = configStore.getBotToken();
         if (!botToken)
           throw new Error(
@@ -617,9 +631,16 @@ export default function (pi: Pi.ExtensionAPI) {
           tokenSha256: Journal.createTelegramUpdateJournalBotIdentity({
             botToken,
           }).tokenSha256,
+          admissionProfileKey: authority.ledger.getProfileKey(),
         });
       },
       runWorkspaceOperation: telegramWorkspaceOperationRuntime.run,
+      deleteThread(authorize) {
+        return directTelegramApiRuntime.deleteWorkspaceThread(authorize);
+      },
+      onError(error) {
+        recordRuntimeEvent("telegram", error, { phase: "manual-inactive-thread-cleanup" });
+      },
     });
   const updateAdmissionRuntimeBinding =
     Updates.createTelegramUpdateAdmissionRuntimeBinding<Pi.ExtensionContext>({
@@ -1187,7 +1208,8 @@ export default function (pi: Pi.ExtensionAPI) {
       sendInteractiveMessage,
       answerCallbackQuery,
       ...configControls,
-      reviewInactiveThreads: inactiveThreadCleanupReviewRuntime.review,
+      reviewInactiveThreads: inactiveThreadCleanupRuntime.review,
+      cleanInactiveThreads: inactiveThreadCleanupRuntime.clean,
       getThreadDisplayMode() {
         return threadStore.getBotState().threadMode === "enabled"
           ? Config.resolveTelegramThreadDisplayMode(configStore.get())
@@ -1342,6 +1364,27 @@ export default function (pi: Pi.ExtensionAPI) {
     },
     getAdmissionScope: getTelegramUpdateAdmissionScope,
     getAdmissionJournalBinding: getTelegramQueueJournalBinding,
+    getCommandReplyTarget(message) {
+      if (
+        message.chat.type !== "private" ||
+        "business_connection_id" in message ||
+        !Updates.getTelegramUpdateExecutionFence(message) ||
+        lockRuntime.owns()
+      ) return undefined;
+      Updates.assertTelegramUpdateExecutionCurrent(message);
+      const binding = resolveTelegramFollowerJournalBinding();
+      const target = telegramBusFollowerRegistrationState.getTarget();
+      if (
+        !telegramBusFollowerRegistrationState.isRegistered() ||
+        !binding ||
+        binding.recoveryKey !==
+          followerAdmissionLifecycleRuntime.getJournalBindingKey() ||
+        !target ||
+        (threadStore.getBotState().threadMode === "enabled" &&
+          target.threadId === undefined)
+      ) throw new Error("Telegram command reply lost its registered recipient.");
+      return { ...target };
+    },
     beginCommandEffectWork: publicationRuntime.beginWork,
     getMessageOwnership: messageOwnershipRuntime.getForwardOwnership,
     recordMessageOwnership: messageOwnershipRuntime.recordRouted,

package/node_modules/@llblab/pi-telegram/lib/generative-apps.ts

@@ -288,6 +288,18 @@ export function resolveGenerativeAppDir(agentDir: string, app: string): string {
   return join(getAppsRoot(agentDir), app);
 }
 
+export async function isGenerativeAppInstalled(
+  agentDir: string,
+  app: string,
+): Promise<boolean> {
+  try {
+    await stat(resolveGenerativeAppModulePath(agentDir, app));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export function resolveGenerativeAppModulePath(
   agentDir: string,
   app: string,

package/node_modules/@llblab/pi-telegram/lib/lifecycle.ts

@@ -14,6 +14,7 @@ import type {
   AgentStartEvent,
   AssistantMessageEvent,
   BeforeAgentStartEvent,
+  BeforeAgentStartEventResult,
   ExtensionAPI,
   ExtensionContext,
   InputEvent,
@@ -61,6 +62,7 @@ type TelegramBeforeAgentStartEvent = Omit<
 
 export interface TelegramBeforeAgentStartResult {
   systemPrompt?: string | string[];
+  message?: BeforeAgentStartEventResult["message"];
 }
 
 type TelegramBeforeAgentStartReturn =

package/node_modules/@llblab/pi-telegram/lib/menu-settings.ts

@@ -90,7 +90,7 @@ export interface TelegramSettingsMenuCallbackDeps extends TelegramSettingsMutati
 export interface TelegramSettingsMenuRuntime<TContext> {
   openSettingsMenu: (
     chatId: number,
-    replyToMessageId: number,
+    replyToMessageId: number | undefined,
     ctx: TContext,
     threadId?: number,
     options?: Pick<TelegramApiCallOptions, "assertAuthority">,
@@ -207,7 +207,7 @@ export function buildAutomaticThreadCleanupSettingsText(
     "<code>-</code> <code>on</code> (default): delete the bound thread and release Telegram authority on graceful quit.",
     "<code>-</code> <code>off</code>: preserve the tab as a restart hint; manual <code>/telegram-disconnect</code> still confirms and deletes it.",
     "",
-    "Review inactive tabs checks current owner and work evidence. Review never deletes tabs.",
+    "On the leader instance, Review inactive tabs checks current owner and work evidence, including tabs without a letter. Review never deletes tabs.",
   ].join("\n");
 }
 
@@ -217,7 +217,8 @@ function buildInactiveThreadReviewText(count: number): string {
     "",
     `${count} proven inactive tab${count === 1 ? "" : "s"}.`,
     "No tabs were deleted.",
-    "Deletion requires a separate confirmed Clean action.",
+    "Clean inactive tabs deletes these Telegram tabs and all their messages. Pi session history and project files are not removed.",
+    "Clean rechecks owner and work protection; a changed or protected tab is skipped. Choose Back to leave without deleting anything.",
   ].join("\n");
 }
 

package/node_modules/@llblab/pi-telegram/lib/menu.ts

@@ -264,7 +264,7 @@ export interface TelegramMenuActionRuntimeDeps<
   canOfferInFlightModelSwitch: (ctx: TContext) => boolean;
   sendTextReply: (
     chatId: number,
-    replyToMessageId: number,
+    replyToMessageId: number | undefined,
     text: string,
     options?: {
       target?: { chatId: number; threadId?: number };
@@ -294,21 +294,21 @@ export interface TelegramMenuActionRuntime<
   ) => Promise<void>;
   sendStatusMessage: (
     chatId: number,
-    replyToMessageId: number,
+    replyToMessageId: number | undefined,
     ctx: TContext,
     threadId?: number,
     options?: Pick<TelegramApiCallOptions, "assertAuthority">,
   ) => Promise<void>;
   openModelMenu: (
     chatId: number,
-    replyToMessageId: number,
+    replyToMessageId: number | undefined,
     ctx: TContext,
     threadId?: number,
     options?: Pick<TelegramApiCallOptions, "assertAuthority">,
   ) => Promise<void>;
   openThinkingMenu: (
     chatId: number,
-    replyToMessageId: number,
+    replyToMessageId: number | undefined,
     ctx: TContext,
     threadId?: number,
     options?: Pick<TelegramApiCallOptions, "assertAuthority">,

package/node_modules/@llblab/pi-telegram/lib/pi.ts

@@ -10,6 +10,7 @@ import {
   type AgentSettledEvent,
   type AgentStartEvent,
   type BeforeAgentStartEvent,
+  type BeforeAgentStartEventResult,
   type ExtensionAPI,
   type ExtensionCommandContext,
   type ExtensionContext,
@@ -33,6 +34,7 @@ export type {
   AgentStartEvent,
   AssistantMessageEvent,
   BeforeAgentStartEvent,
+  BeforeAgentStartEventResult,
   ExtensionAPI,
   ExtensionCommandContext,
   ExtensionContext,