@llblab/pi-kit 0.18.1 → 0.19.0

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

@@ -4,6 +4,8 @@
  * Owns Telegram slash-command normalization, bot command metadata, pi-side command registration, and command-initiated session replacement orchestration behind runtime ports
  */
 
+import { randomUUID } from "node:crypto";
+
 import {
   pairTelegramUserIfNeeded,
   type TelegramConfigStore,
@@ -366,7 +368,6 @@ export function createTelegramBotCommandRegistrar(
 export interface TelegramBridgeCommandStartPollingOptions {
   force?: boolean;
   forceFreshLeaderThread?: boolean;
-  requestedThreadName?: string;
 }
 
 export interface TelegramBridgeCommandStartPollingResult {
@@ -407,7 +408,6 @@ export interface TelegramBridgeCommandRegistrationDeps {
     ctx: ExtensionCommandContext,
     profileName: string,
   ) => Promise<boolean>;
-  validateThreadName?: (threadName: string) => string | undefined;
 }
 
 export type TelegramThreadDisplayNameRenamePort = (
@@ -466,17 +466,6 @@ function parseTelegramProfileArg(args: string): string | undefined {
   return word === TELEGRAM_DEFAULT_PROFILE_NAME ? undefined : word;
 }
 
-export function parseTelegramRequestedThreadName(
-  args: string,
-): string | undefined {
-  const token = args
-    .trim()
-    .split(/\s+/)
-    .find((word) => /^as=/i.test(word));
-  const value = token?.slice(3).trim();
-  return value || undefined;
-}
-
 function formatTelegramTakeoverTitle(ctx: ExtensionCommandContext): string {
   return ctx.ui.theme.fg("accent", "pi-telegram");
 }
@@ -498,7 +487,7 @@ export function registerTelegramBridgeCommands(
   deps: TelegramBridgeCommandRegistrationDeps,
 ): void {
   pi.registerCommand("telegram-setup", {
-    description: "Configure Telegram bot token. Use /telegram-setup <name> for named profiles.",
+    description: "<profile> — Configure Telegram bot token",
     handler: async (args, ctx) => {
       await deps.promptForConfig(ctx, parseTelegramProfileArg(args));
     },
@@ -513,28 +502,17 @@ export function registerTelegramBridgeCommands(
     },
   });
   pi.registerCommand("telegram-connect", {
-    description:
-      "Start the Telegram bridge. Use /telegram-connect <profile> and optional as=Name for a fresh Workspace Thread.",
+    description: "<profile> — Start Telegram bridge",
     handler: async (args, ctx) => {
-      const profileName = parseTelegramProfileArg(args);
-      const requestedNameTokens = args
-        .trim()
-        .split(/\s+/)
-        .filter((word) => /^as=/i.test(word));
-      const requestedThreadName = parseTelegramRequestedThreadName(args);
-      const requestedNameError =
-        requestedNameTokens.length > 1
-          ? "Specify at most one as=Name Workspace Thread name."
-          : requestedNameTokens.length === 1 && !requestedThreadName
-            ? "Usage: /telegram-connect [profile] as=Flightprice"
-            : requestedThreadName
-              ? deps.validateThreadName?.(requestedThreadName)
-              : undefined;
-      if (requestedNameError) {
-        ctx.ui.notify(requestedNameError, "warning");
+      if (args.trim().split(/\s+/).some((word) => /^as=/i.test(word))) {
+        ctx.ui.notify(
+          "Thread names are configured from Telegram, not from Pi commands.",
+          "warning",
+        );
         deps.updateStatus(ctx);
         return;
       }
+      const profileName = parseTelegramProfileArg(args);
       if (profileName && deps.activateProfileConfig) {
         const ok = await deps.activateProfileConfig(ctx, profileName);
         if (!ok) {
@@ -597,7 +575,6 @@ export function registerTelegramBridgeCommands(
       };
       let result = await startWithRecovery({
         forceFreshLeaderThread: true,
-        ...(requestedThreadName ? { requestedThreadName } : {}),
       });
       if (result && !result.ok && result.canTakeover) {
         const confirmed = await ctx.ui.confirm(
@@ -612,7 +589,6 @@ export function registerTelegramBridgeCommands(
         result = await startWithRecovery({
           force: true,
           forceFreshLeaderThread: true,
-          ...(requestedThreadName ? { requestedThreadName } : {}),
         });
       }
       if (result?.message) {
@@ -625,8 +601,7 @@ export function registerTelegramBridgeCommands(
     },
   });
   pi.registerCommand("telegram-disconnect", {
-    description:
-      "Stop Telegram; in Threaded Mode, delete this instance's current thread",
+    description: "Stop Telegram and delete current thread in Threaded Mode",
     handler: async (_args, ctx) => {
       const threadName = deps.getDisconnectThreadName?.();
       if (threadName) {
@@ -2337,7 +2312,7 @@ async function handleTelegramCommandRuntime<
 
 export const TELEGRAM_INTERNAL_COMMAND_NAME = "telegram-internal";
 export const TELEGRAM_INTERNAL_COMMAND_DESCRIPTION =
-  "(internal) dispatch one settled Telegram lifecycle action";
+  "Internal Telegram command cannot be run manually";
 export const TELEGRAM_INTERNAL_MANUAL_USE_MESSAGE =
   "This internal Telegram command cannot be run manually.";
 
@@ -2542,6 +2517,7 @@ export function createTelegramSessionActionAssembly(
 
 type TelegramPendingInternalAction = {
   kind: "replace-session";
+  token: string;
   updateId: number;
   target: { chatId: number; threadId?: number; messageId: number };
 };
@@ -2582,9 +2558,9 @@ export function createTelegramSessionActionRuntime(
       registered = true;
       deps.registerCommand(TELEGRAM_INTERNAL_COMMAND_NAME, {
         description: TELEGRAM_INTERNAL_COMMAND_DESCRIPTION,
-        handler: async (_args, ctx) => {
+        handler: async (args, ctx) => {
           const action = pendingAction;
-          if (!action) {
+          if (!action || args.trim() !== action.token) {
             ctx.ui.notify(TELEGRAM_INTERNAL_MANUAL_USE_MESSAGE, "warning");
             return;
           }
@@ -2616,10 +2592,11 @@ export function createTelegramSessionActionRuntime(
       const target = pendingTarget;
       pendingTarget = undefined;
       if (!target) return;
-      pendingAction = { kind: "replace-session", updateId, target };
+      const token = randomUUID();
+      pendingAction = { kind: "replace-session", token, updateId, target };
       void Promise.resolve()
         .then(() =>
-          deps.sendUserMessage(`/${TELEGRAM_INTERNAL_COMMAND_NAME}`, {
+          deps.sendUserMessage(`/${TELEGRAM_INTERNAL_COMMAND_NAME} ${token}`, {
             expandPromptTemplates: true,
           }),
         )

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

@@ -871,6 +871,7 @@ export default function (pi: Pi.ExtensionAPI) {
     storeModelMenuState: modelMenuRuntime.storeState,
     updateStatusMessage: menuActions.updateStatusMessage,
     updateStatus,
+    dismissGuestPlaceholder: guestPlaceholderRuntime.dismiss,
   });
   const threadDisplaySettingsRuntime =
     ThreadDisplay.createTelegramThreadDisplaySettingsRuntime({
@@ -1731,14 +1732,6 @@ export default function (pi: Pi.ExtensionAPI) {
       if (!record?.target.threadId) return undefined;
       return record.threadName ?? "current Telegram thread";
     },
-    setRequestedThreadNameForPollingStart:
-      telegramThreadCapabilityState.setRequestedThreadName,
-    validateThreadName(threadName) {
-      return Threads.getTelegramTopicThreadNameValidationError(
-        threadName,
-        undefined,
-      );
-    },
     onTransportChanged() {
       deliveryLifecycleRuntime.onSessionStart();
       activityVerbosityRuntime.reset();

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

@@ -31,6 +31,8 @@ type TelegramQueueMenuReplyMarkup = TelegramInlineKeyboardMarkup;
 interface TelegramQueueMenuItem {
   chatId: number;
   replyToMessageId: number;
+  queueOrder: number;
+  isGuest: boolean;
   queuePosition: number;
   isPriority: boolean;
   priorityEmoji?: string;
@@ -60,6 +62,8 @@ function toTelegramQueueMenuItems<Context>(
     return {
       chatId: item.chatId,
       replyToMessageId: item.replyToMessageId,
+      queueOrder: item.queueOrder,
+      isGuest: item.kind === "prompt" && item.guestQueryId !== undefined,
       queuePosition: index + 1,
       isPriority: item.queueLane === "priority",
       priorityEmoji: item.kind === "prompt" ? item.priorityEmoji : undefined,
@@ -106,7 +110,9 @@ function buildTelegramQueueMenuReplyMarkup(
     return [
       {
         text: label,
-        callback_data: `queue:pick:${item.chatId}:${item.replyToMessageId}`,
+        callback_data: item.isGuest
+          ? `queue:guest-pick:${item.queueOrder}`
+          : `queue:pick:${item.chatId}:${item.replyToMessageId}`,
       },
     ];
   });
@@ -178,6 +184,22 @@ function getTelegramQueueMenuItemText(item: TelegramQueueMenuItem): string {
   return `${heading}\n${preview}`;
 }
 
+function buildTelegramGuestQueueItemSubmenuReplyMarkup(
+  queueOrder: number,
+): TelegramQueueMenuReplyMarkup {
+  return {
+    inline_keyboard: [
+      [{ text: "⬆️ Back", callback_data: "queue:list" }],
+      [
+        {
+          text: "🔴 Skip",
+          callback_data: `queue:guest-skip:${queueOrder}`,
+        },
+      ],
+    ],
+  };
+}
+
 function buildTelegramQueueItemSubmenuReplyMarkup(
   chatId: number,
   replyToMessageId: number,
@@ -217,6 +239,8 @@ interface TelegramQueueMenuCallbackDeps<Context = unknown> {
     chatId: number,
     replyToMessageId: number,
   ) => TelegramQueueMenuItem | undefined;
+  findGuestItem: (queueOrder: number) => TelegramQueueMenuItem | undefined;
+  skipGuest: (queueOrder: number, ctx: Context) => Promise<boolean>;
   togglePriority: (chatId: number, replyToMessageId: number) => boolean;
   setPriority: (
     chatId: number,
@@ -275,6 +299,38 @@ async function handleTelegramQueueMenuCallback<Context>(
     );
     return true;
   }
+  const guestPickMatch = data.match(/^queue:guest-pick:(\d+)$/);
+  if (guestPickMatch) {
+    await handleTelegramGuestQueueMenuPick(
+      callbackQueryId,
+      replyChatId,
+      replyMessageId,
+      Number(guestPickMatch[1]),
+      deps,
+    );
+    return true;
+  }
+  const guestSkipMatch = data.match(/^queue:guest-skip:(\d+)$/);
+  if (guestSkipMatch) {
+    const skipped = await deps.skipGuest(Number(guestSkipMatch[1]), ctx);
+    if (!skipped) {
+      await refreshStaleTelegramQueueMenuItem(
+        callbackQueryId,
+        replyChatId,
+        replyMessageId,
+        deps,
+      );
+      return true;
+    }
+    await updateTelegramQueueMenuList(
+      callbackQueryId,
+      replyChatId,
+      replyMessageId,
+      deps,
+      "Guest prompt skipped.",
+    );
+    return true;
+  }
   const pickMatch = data.match(/^queue:pick:(\d+):(\d+)$/);
   if (pickMatch) {
     await handleTelegramQueueMenuPick(
@@ -379,6 +435,31 @@ async function refreshStaleTelegramQueueMenuItem<Context>(
   );
 }
 
+async function handleTelegramGuestQueueMenuPick<Context>(
+  callbackQueryId: string,
+  replyChatId: number,
+  replyMessageId: number,
+  queueOrder: number,
+  deps: TelegramQueueMenuCallbackDeps<Context>,
+): Promise<void> {
+  const item = deps.findGuestItem(queueOrder);
+  if (!item) {
+    return refreshStaleTelegramQueueMenuItem(
+      callbackQueryId,
+      replyChatId,
+      replyMessageId,
+      deps,
+    );
+  }
+  await deps.updateQueueMessage(
+    replyChatId,
+    replyMessageId,
+    getTelegramQueueMenuItemText(item),
+    buildTelegramGuestQueueItemSubmenuReplyMarkup(queueOrder),
+  );
+  await deps.answerCallbackQuery(callbackQueryId);
+}
+
 async function handleTelegramQueueMenuPick<Context>(
   callbackQueryId: string,
   replyChatId: number,
@@ -606,6 +687,7 @@ export function createTelegramQueueMenuRuntime<
     ctx: Context,
   ) => Promise<void>;
   updateStatus: (ctx: Context) => void;
+  dismissGuestPlaceholder?: (inlineMessageId: string) => Promise<void>;
 }): TelegramQueueMenuRuntime<Context> {
   const sendQueueMenuMessage = createQueueMenuSendMessageAdapter(
     deps.sendInteractiveMessage,
@@ -628,6 +710,7 @@ export function createTelegramQueueMenuRuntime<
       updateStatusMessage: deps.updateStatusMessage,
       answerCallbackQuery: deps.answerCallbackQuery,
       updateStatus: deps.updateStatus,
+      dismissGuestPlaceholder: deps.dismissGuestPlaceholder,
     }),
   };
 }
@@ -695,6 +778,7 @@ function createQueueMenuCallbackHandler<
     text?: string,
   ) => Promise<void>;
   updateStatus: (ctx: Context) => void;
+  dismissGuestPlaceholder?: (inlineMessageId: string) => Promise<void>;
 }) {
   return async (
     query: TelegramQueueMenuCallbackQuery,
@@ -737,6 +821,11 @@ function createQueueMenuCallbackHandler<
     const findItem = (cId: number, rId: number) => {
       return findTelegramQueueMenuItem(toMenuItems(), cId, rId);
     };
+    const findGuestItem = (queueOrder: number) => {
+      return toMenuItems().find((item) => {
+        return item.isGuest && item.queueOrder === queueOrder;
+      });
+    };
     return handleTelegramQueueMenuCallback(
       query.id,
       data,
@@ -746,6 +835,14 @@ function createQueueMenuCallbackHandler<
       {
         getQueuedItems: toMenuItems,
         findItem,
+        findGuestItem,
+        skipGuest: (queueOrder, callbackContext) => {
+          return skipQueuedTelegramGuestPrompt(queueOrder, callbackContext, {
+            getQueueSnapshot,
+            queueMutationRuntime: deps.queueMutationRuntime,
+            dismissGuestPlaceholder: deps.dismissGuestPlaceholder,
+          });
+        },
         togglePriority: (cId, rId) => {
           return toggleQueuedTelegramPromptPriority(cId, rId, ctx, {
             getQueueSnapshot,
@@ -772,6 +869,34 @@ function createQueueMenuCallbackHandler<
   };
 }
 
+async function skipQueuedTelegramGuestPrompt<Context>(
+  queueOrder: number,
+  ctx: Context,
+  deps: {
+    getQueueSnapshot: () => Queue.TelegramQueueItem<Context>[];
+    queueMutationRuntime: Queue.TelegramQueueMutationController<Context>;
+    dismissGuestPlaceholder?: (inlineMessageId: string) => Promise<void>;
+  },
+): Promise<boolean> {
+  const item = deps.getQueueSnapshot().find((candidate) => {
+    return candidate.kind === "prompt" &&
+      candidate.guestQueryId !== undefined &&
+      candidate.queueOrder === queueOrder;
+  });
+  if (!item || !deps.queueMutationRuntime.removeGuestPromptByQueueOrder) {
+    return false;
+  }
+  const removed = deps.queueMutationRuntime.removeGuestPromptByQueueOrder(
+    queueOrder,
+    ctx,
+  );
+  if (!removed) return false;
+  if (item.guestInlineMessageId && deps.dismissGuestPlaceholder) {
+    await deps.dismissGuestPlaceholder(item.guestInlineMessageId);
+  }
+  return true;
+}
+
 function getQueueMenuReactionDisposition<Context>(
   item: Queue.TelegramQueueItem<Context>,
   priority: boolean,

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

@@ -922,6 +922,28 @@ export function removeTelegramQueueItemsByMessageIds<TContext = unknown>(
   };
 }
 
+export function removeTelegramQueuedGuestPromptByOrder<TContext = unknown>(
+  items: TelegramQueueItem<TContext>[],
+  queueOrder: number,
+): {
+  items: TelegramQueueItem<TContext>[];
+  removedItems: PendingTelegramTurn[];
+  removedCount: number;
+} {
+  const index = items.findIndex((item) => {
+    return isPendingTelegramTurn(item) &&
+      item.guestQueryId !== undefined &&
+      item.queueOrder === queueOrder;
+  });
+  if (index < 0) return { items, removedItems: [], removedCount: 0 };
+  const removedItem = items[index] as PendingTelegramTurn;
+  return {
+    items: [...items.slice(0, index), ...items.slice(index + 1)],
+    removedItems: [removedItem],
+    removedCount: 1,
+  };
+}
+
 export function applyTelegramQueuePromptReactionDisposition<
   TContext = unknown,
 >(
@@ -2331,6 +2353,10 @@ export interface TelegramQueueMutationController<TContext> {
     ctx: TContext,
     scope?: TelegramQueueMessageScope,
   ) => number;
+  removeGuestPromptByQueueOrder?: (
+    queueOrder: number,
+    ctx: TContext,
+  ) => boolean;
   applyReactionByMessageId: (
     messageId: number,
     disposition: TelegramQueueReactionDisposition,
@@ -2604,6 +2630,11 @@ export function createTelegramQueueMutationController<TContext>(
         buildRuntimeDeps(ctx),
         scope,
       ),
+    removeGuestPromptByQueueOrder: (queueOrder, ctx) =>
+      removeTelegramQueuedGuestPromptByOrderRuntime(
+        queueOrder,
+        buildRuntimeDeps(ctx),
+      ),
     applyReactionByMessageId: (messageId, disposition, ctx, scope) =>
       applyTelegramQueuePromptReactionDispositionRuntime(
         messageId,
@@ -2684,6 +2715,21 @@ export function removeTelegramQueueItemsByMessageIdsRuntime<TContext>(
   return removedCount;
 }
 
+export function removeTelegramQueuedGuestPromptByOrderRuntime<TContext>(
+  queueOrder: number,
+  deps: TelegramQueueMutationRuntimeDeps<TContext>,
+): boolean {
+  const { items, removedItems, removedCount } =
+    removeTelegramQueuedGuestPromptByOrder(deps.getQueuedItems(), queueOrder);
+  if (removedCount === 0) return false;
+  // A menu Skip means permanent discard, so settle durable admission before
+  // removing the live item. A failed settlement keeps the prompt retryable.
+  deps.onItemsDiscarded?.(removedItems, deps.ctx);
+  deps.setQueuedItems(items);
+  updateTelegramQueueStatusRuntime(deps);
+  return true;
+}
+
 export function applyTelegramQueuePromptReactionDispositionRuntime<TContext>(
   messageId: number,
   disposition: TelegramQueueReactionDisposition,

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

@@ -1018,6 +1018,10 @@ export const TELEGRAM_GUEST_PLACEHOLDER_FRAMES = [
   "<b>🌏 Working on it...</b>",
 ] as const;
 
+// Telegram does not expose deletion for inline messages. This non-printing,
+// non-empty edit visually clears a guest placeholder after its query is skipped.
+export const TELEGRAM_DISMISSED_GUEST_PLACEHOLDER_TEXT = "\u2063";
+
 export function buildTelegramGuestPlaceholderFrame(step: number): string {
   const frames: readonly string[] = TELEGRAM_GUEST_PLACEHOLDER_FRAMES;
   const index = ((step % frames.length) + frames.length) % frames.length;
@@ -1052,6 +1056,8 @@ export interface TelegramGuestPlaceholderRuntime {
   stop: (inlineMessageId: string) => Promise<void>;
   /** Cancels every loop without waiting for in-flight edits (session shutdown). */
   stopAll: () => void;
+  /** Stops rotation and visually clears the inline placeholder. */
+  dismiss: (inlineMessageId: string) => Promise<void>;
 }
 
 interface TelegramGuestPlaceholderSession {
@@ -1202,5 +1208,18 @@ export function createTelegramGuestPlaceholderRuntime(
       }
       sessions.clear();
     },
+    async dismiss(inlineMessageId) {
+      await stop(inlineMessageId);
+      try {
+        await deps.editGuestInlineMessage(inlineMessageId, {
+          text: TELEGRAM_DISMISSED_GUEST_PLACEHOLDER_TEXT,
+          parseMode: "HTML",
+        });
+      } catch (error) {
+        deps.recordRuntimeEvent?.("guest", error, {
+          phase: "guest-placeholder-dismiss",
+        });
+      }
+    },
   };
 }

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

@@ -684,7 +684,14 @@ export async function ensureTelegramLeaderThreadBinding(
     assertLeaderEpoch("before-workspace-persist");
     await deps.topicTargetStore.persist();
     assertLeaderEpoch("after-workspace-persist");
-    return { ...result, ...(committed.displayTitle ? { displayTitle: committed.displayTitle } : {}) };
+    const { target: _target, slot: _slot, threadName: _threadName, displayTitle: _displayTitle, ...rest } = result;
+    return {
+      ...rest,
+      target: { ...committed.target },
+      slot: committed.slot ?? result.slot,
+      ...(committed.threadName ? { threadName: committed.threadName } : {}),
+      ...(committed.displayTitle ? { displayTitle: committed.displayTitle } : {}),
+    };
   };
   try {
   const unavailableTargetKeys = new Set([

package/node_modules/@llblab/pi-telegram/package.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -44,8 +44,8 @@
     "@llblab/pi-clean-room": "0.1.1",
     "@llblab/pi-codex-usage": "0.10.0",
     "@llblab/pi-grow-loop": "0.8.1",
-    "@llblab/pi-state-flow": "0.16.3",
-    "@llblab/pi-telegram": "0.50.0",
+    "@llblab/pi-state-flow": "0.17.2",
+    "@llblab/pi-telegram": "0.50.1",
     "@llblab/skills": "1.15.0"
   },
   "bundledDependencies": [

package/node_modules/@llblab/pi-state-flow/dist/lib/discovery.d.ts

@@ -1,21 +0,0 @@
-import { type ArtifactSourceIdentity } from "./artifact.ts";
-/** Opaque source metadata discovered without decoding or retaining Markdown bodies. */
-export interface ArtifactSourceCandidate extends ArtifactSourceIdentity {
-    /** Raw byte count used as a conservative maintenance token-budget ceiling. */
-    bytes: number;
-}
-export interface GlobalMarkdownDiscoveryResult {
-    sources: ArtifactSourceCandidate[];
-    removed: string[];
-    unavailable?: string;
-}
-export declare function getKnowledgeRoot(agentDir?: string): string;
-/** Discover regular `*.md` files beneath a Knowledge root without following directory or file symlinks. */
-export declare function discoverGlobalMarkdownSources(knowledgeRoot?: string): ArtifactSourceCandidate[];
-/** Source-owner discovery; retained paths let restart/status re-observe removals until publication. */
-export declare class GlobalMarkdownDiscovery {
-    #private;
-    readonly knowledgeRoot: string;
-    constructor(knowledgeRoot?: string);
-    refresh(retainedPaths?: Iterable<string>): GlobalMarkdownDiscoveryResult;
-}