@llblab/pi-kit 0.10.6 → 0.10.7

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to `@llblab/pi-kit` are documented here.
 
+## 0.10.7 - 2026-09-12
+
+- `Queue Enqueue`: Advances the exact Telegram pin to `0.45.7`, preventing asynchronous voice/file preparation from restoring consumed prompts or overwriting newer queue changes. Surviving history and receipts follow current queue state; an already-wedged in-memory queue still requires separately authorized recovery. The package set, resource inventory, and load order remain unchanged.
+
 ## 0.10.6 - 2026-09-12
 
 - `Guest Placeholder And Delivery`: Advances the exact Telegram pin to `0.45.6`, so the guest ACK rotates the globe placeholder in whole cycles and holds `🌏 Working on it...`, guest answers are still delivered when a companion extension suppresses the final assistant message, `429` retry waits are recorded as `api` runtime events, the Thread display settings card drops the manual `/name` hint, and empty-queue headings carry no trailing period. The package set, resource inventory, and explicit load order remain unchanged.

package/README.md

@@ -15,7 +15,7 @@ Package links lead to the owning repositories for usage, documentation, issues,
 | [`@llblab/pi-codex-usage`](https://github.com/llblab/pi-codex-usage) | `0.9.4` | Compact Codex/Spark subscription-limit status |
 | [`@llblab/pi-grow-loop`](https://github.com/llblab/pi-grow-loop) | `0.8.1` | Visible continuation scheduling and bounded worker Skills |
 | [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.9.6` | Atomic scoped state cohorts with final-eligibility resolution |
-| [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.45.6` | Telegram companion, queues, files, voice, controls, and Generative Apps guidance |
+| [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.45.7` | Telegram companion, queues, files, voice, controls, and Generative Apps guidance |
 | [`@llblab/skills`](https://github.com/llblab/skills) | `1.15.0` | Portable workflows for engineering, review, design, context maintenance, and other focused tasks |
 
 Versions are exact by design. An upstream release does not change an installed kit until this repository explicitly advances the dependency and publishes a new kit version. Runtime defects and package-specific feature requests belong in the linked repository; package selection and kit installation issues belong here.

package/node_modules/@llblab/pi-telegram/BACKLOG.md

@@ -2,6 +2,7 @@
 
 _This file owns unresolved project work only. Completed behavior belongs in `CHANGELOG.md`; durable contracts belong in `AGENTS.md` and `/docs`._
 
+- [ ] `Prompt enqueue hotfix` (`optional`, `operator-gated`): Optional nonblocking operator-authorized disposable-follower smoke: overlap delayed voice processing with turn completion and confirm one-time ordered consumption and truthful counts against the [queue contract](./docs/architecture.md#queue-and-dispatch-safety). Separately authorized supported recovery investigation remains open: prevention does not repair an already-wedged in-memory queue; establish the exact recovery path and preservation/discard consequences before mutation, otherwise report the blocker. No journal/ownership edits, replay of settled input, implicit queue clearing, or restart; live activation requires separate operator authorization.
 - [ ] `Channel multimedia posts` (`0.45.1`, live-acceptance-gated): `telegram_message` channel delivery accepts one local `.jpg`/`.jpeg`/`.png`/`.webp` photo or `.mp4` video, uploads it through the multipart transport as `sendPhoto`/`sendVideo` with `text` as the HTML caption, validates kind and size (photo ≤ 10 MiB, video ≤ 50 MiB) plus ≤ 1024 visible caption characters before issuance, and rejects unsupported types and albums instead of downgrading them to links. The channel-post journal binds kind/file name/byte size/SHA-256 and caption, so duplicate requests and lost acknowledgements never re-upload; media-post edits replace the caption through `editMessageCaption`, and Markdown spoilers render as `<tg-spoiler>`. Live image publication passed on `@llb_log`. Regressions cover confirmed publication, duplicate requests, lost ACK, pre-issuance rejection, caption edits, and reconnect replacement. Remaining: operator-authorized disposable-channel acceptance of rejected upload, duplicate request, and caption edit.
 - [ ] `Manual Thread naming` (`gated-but-preparable`, release priority): Local bot-owned `/name Name` and bare `/name` flows avoid model dispatch. One expiring exact-target input dialog immediately accepts the next valid name, always offers cancel, and offers **Reset to automatic** only while a manual override exists; duplicate/stale callbacks cannot repeat mutation. Durable manual override supersedes every automatic display mode, reset is leader/follower generation- and target-fenced, and Letters remains the default without rewriting recovery identity. Local review findings are remediated, including Bot-API-wait target-replacement regressions for leader/follower rename and reset. Remaining: disposable live acceptance for command-menu ordering, dialog, invalid input, duplicate callbacks, leader/follower rename and reset.
 - [ ] `OMP schema acceptance` ([#267](https://github.com/llblab/pi-telegram/issues/267), `human-/environment-gated`): Local emitted-schema, Pi process, and llama.cpp source checks now prove explicit recursive JSON values, root `$defs`, only supported local `#/...` references, and no bare boolean schema. Confirm one connected `telegram_bind` request through the reporter's OMP + llama-server build before closing interoperability acceptance; do not treat this progressive external check as a Pi release blocker.

package/node_modules/@llblab/pi-telegram/CHANGELOG.md

@@ -4,6 +4,10 @@
 
 ## Unreleased
 
+## 0.45.7: Queue Enqueue Race Hotfix
+
+- `Queue Enqueue`: Asynchronous voice/file preparation no longer restores consumed prompts or overwrites newer queue changes, preventing a settled phantom head from blocking accepted work. Final assembly uses current queue state and allocates order at commit; abort-history folding retains only surviving intended prompts and receipts while preserving a handed-off head until `agent_start`.
+
 ## 0.45.6: Guest Placeholder And Delivery Hotfix
 
 - `Guest Placeholder`: The guest ACK answers with the first bold globe frame (`🌎 Working on it.`) and rotates `🌍`/`🌏` once per second with the dots growing every two seconds. Rotation now completes whole 6-frame cycles and stops only after the 20 s minimum, so a pending answer holds the cycle's final frame (`🌏 Working on it...`) instead of cutting mid-step; a 26 s safety bound stays clear of the ~28 s Telegram flood-control wall, and error backoff and pre-replacement cancellation are unchanged.

package/node_modules/@llblab/pi-telegram/docs/architecture.md

@@ -480,6 +480,8 @@ Menu and reaction controls share the same canonical queue state. A menu Keep can
 
 Admission and planning validate lane contracts. Invalid lane/kind pairings fail predictably instead of being silently coerced.
 
+Prompt preparation completes downloads, inbound handlers, and binary image reads before synchronous final assembly and queue commit. Enqueue captures only intended abort-history identities before preparation; afterward it reads the current queue, folds surviving selected prompts using their current text and receipts, allocates the new turn's order, and appends without another asynchronous boundary. The handed-off head remains in place until `agent_start` consumes it, even if preparation finishes first. Concurrent arrivals, removals, and lane/reaction edits remain intact; preparation failure or stale-generation completion leaves intervening queue changes untouched.
+
 Dispatch requires:
 
 - No active Telegram turn.

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

@@ -2349,16 +2349,18 @@ export interface TelegramControlQueueController<TContext> {
   ) => void;
 }
 
+export type TelegramPreparedPromptTurn = (
+  historyTurns: PendingTelegramTurn[],
+) => PendingTelegramTurn;
+
 export interface TelegramPromptEnqueueRuntimeDeps<
   TMessage,
   TContext = unknown,
 > extends TelegramQueueStore<TContext> {
+  hasPendingDispatch: () => boolean;
   getFoldQueuedPromptsIntoHistory: () => boolean;
   setFoldQueuedPromptsIntoHistory: (fold: boolean) => void;
-  createTurn: (
-    messages: TMessage[],
-    historyTurns: PendingTelegramTurn[],
-  ) => Promise<PendingTelegramTurn>;
+  prepareTurn: (messages: TMessage[]) => Promise<TelegramPreparedPromptTurn>;
   updateStatus: () => void;
   dispatchNextQueuedTelegramTurn: () => void;
   assertExecutionCurrent?: () => void;
@@ -2369,13 +2371,13 @@ export interface TelegramPromptEnqueueControllerDeps<
   TMessage,
   TContext = unknown,
 > extends TelegramQueueStore<TContext> {
+  hasPendingDispatch: () => boolean;
   getFoldQueuedPromptsIntoHistory: () => boolean;
   setFoldQueuedPromptsIntoHistory: (fold: boolean) => void;
-  createTurn: (
+  prepareTurn: (
     messages: TMessage[],
-    historyTurns: PendingTelegramTurn[],
     ctx: TContext,
-  ) => Promise<PendingTelegramTurn>;
+  ) => Promise<TelegramPreparedPromptTurn>;
   updateStatus: (ctx: TContext) => void;
   dispatchNextQueuedTelegramTurn: (ctx: TContext) => void;
   assertExecutionCurrent?: (messages: TMessage[]) => void;
@@ -2727,17 +2729,25 @@ export async function enqueueTelegramPromptTurnRuntime<
   messages: TMessage[],
   deps: TelegramPromptEnqueueRuntimeDeps<TMessage, TContext>,
 ): Promise<PendingTelegramTurn> {
-  const enqueuePlan = planTelegramPromptEnqueue(
+  deps.assertExecutionCurrent?.();
+  const historyOrders = new Set(planTelegramPromptEnqueue(
     deps.getQueuedItems(),
     deps.getFoldQueuedPromptsIntoHistory(),
-  );
-  deps.assertExecutionCurrent?.();
+  ).historyTurns.map((turn) => turn.queueOrder));
   deps.setFoldQueuedPromptsIntoHistory(false);
-  const turn = await deps.createTurn(messages, enqueuePlan.historyTurns);
+  const buildTurn = await deps.prepareTurn(messages);
   deps.assertExecutionCurrent?.();
-  deps.setQueuedItems(
-    appendTelegramQueueItem(enqueuePlan.remainingItems, turn),
-  );
+  // Preserve the Pi-owned head until agent_start, plus later arrivals and current edits/reactions.
+  const pendingDispatch = deps.hasPendingDispatch();
+  const historyTurns: PendingTelegramTurn[] = [];
+  const remainingItems = deps.getQueuedItems().filter((item, index) => {
+    if ((pendingDispatch && index === 0) || !isPendingTelegramTurn(item) ||
+        !historyOrders.has(item.queueOrder)) return true;
+    historyTurns.push(item);
+    return false;
+  });
+  const turn = buildTurn(historyTurns);
+  deps.setQueuedItems(appendTelegramQueueItem(remainingItems, turn));
   deps.onQueued?.(turn);
   deps.updateStatus();
   deps.dispatchNextQueuedTelegramTurn();
@@ -2754,8 +2764,7 @@ export function createTelegramPromptEnqueueController<
     enqueue: (messages, ctx, onQueued) =>
       enqueueTelegramPromptTurnRuntime(messages, {
         ...deps,
-        createTurn: (nextMessages, historyTurns) =>
-          deps.createTurn(nextMessages, historyTurns, ctx),
+        prepareTurn: (nextMessages) => deps.prepareTurn(nextMessages, ctx),
         updateStatus: () => deps.updateStatus(ctx),
         dispatchNextQueuedTelegramTurn: () =>
           deps.dispatchNextQueuedTelegramTurn(ctx),

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

@@ -2095,7 +2095,7 @@ export function createTelegramInboundRouteRuntime<
     }
     await menuCallbackHandler(query, ctx);
   };
-  const promptTurnBuilder = Turns.createTelegramPromptTurnRuntimeBuilder<
+  const preparePromptTurn = Turns.createTelegramPromptTurnRuntimePreparer<
     TMessage,
     TContext
   >({
@@ -2124,7 +2124,8 @@ export function createTelegramInboundRouteRuntime<
       text: "continue",
       caption: undefined,
     } as TMessage;
-    const turn = await promptTurnBuilder([continueMessage], [], ctx);
+    const buildTurn = await preparePromptTurn([continueMessage], ctx);
+    const turn = buildTurn([]);
     const continueTurn = {
       ...turn,
       queueLane: "control" as const,
@@ -2262,15 +2263,19 @@ export function createTelegramInboundRouteRuntime<
   const promptEnqueueController =
     Queue.createTelegramPromptEnqueueController<TMessage, TContext>({
       ...deps.telegramQueueStore,
+      hasPendingDispatch: deps.bridgeRuntime.lifecycle.hasDispatchPending,
       getFoldQueuedPromptsIntoHistory:
         deps.bridgeRuntime.lifecycle.shouldFoldQueuedPromptsIntoHistory,
       setFoldQueuedPromptsIntoHistory:
         deps.bridgeRuntime.lifecycle.setFoldQueuedPromptsIntoHistory,
-      createTurn: async (messages, historyTurns, turnCtx) => {
-        const turn = await promptTurnBuilder(messages, historyTurns, turnCtx);
-        return turn.replyToMessageId > 0
-          ? turn
-          : { ...turn, replyToMessageId: 0 };
+      prepareTurn: async (messages, turnCtx) => {
+        const buildTurn = await preparePromptTurn(messages, turnCtx);
+        return (historyTurns) => {
+          const turn = buildTurn(historyTurns);
+          return turn.replyToMessageId > 0
+            ? turn
+            : { ...turn, replyToMessageId: 0 };
+        };
       },
       updateStatus: deps.updateStatus,
       dispatchNextQueuedTelegramTurn: requestDispatchNextQueuedTelegramTurn,

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

@@ -26,6 +26,7 @@ import {
   createTelegramQueueAdmissionReceipt,
   truncateTelegramQueueSummary,
   type PendingTelegramTurn,
+  type TelegramPreparedPromptTurn,
   type TelegramPromptContent,
   type TelegramQueueAdmissionReceipt,
   type TelegramQueueItem,
@@ -454,17 +455,16 @@ export interface TelegramPromptTurnRuntimeBuilderDeps<
   assertExecutionCurrent?: (message: TelegramTurnMessage) => void;
 }
 
-export function createTelegramPromptTurnRuntimeBuilder<
+export function createTelegramPromptTurnRuntimePreparer<
   TMessage extends TelegramTurnMessage & TelegramMediaMessage,
   TContext = unknown,
 >(
   deps: TelegramPromptTurnRuntimeBuilderDeps<TContext>,
 ): (
   messages: TMessage[],
-  historyTurns?: PendingTelegramTurn[],
   ctx?: TContext,
-) => Promise<PendingTelegramTurn> {
-  return async (messages, historyTurns = [], ctx) => {
+) => Promise<TelegramPreparedPromptTurn> {
+  return async (messages, ctx) => {
     const rawText = extractTelegramMessagesText(messages);
     const firstMessage = messages[0];
     if (firstMessage) deps.assertExecutionCurrent?.(firstMessage);
@@ -577,11 +577,10 @@ export function createTelegramPromptTurnRuntimeBuilder<
       thread: threadLabel,
       "from-thread": firstMessage?.pi_telegram_agent_source_thread,
     });
-    return buildTelegramPromptTurnRuntime({
+    const buildTurn = await prepareTelegramPromptTurn({
       telegramPrefix,
       messages,
-      historyTurns,
-      queueOrder: deps.allocateQueueOrder(),
+      readBinaryFile: readFile,
       rawText: promptRawText,
       sourceContext,
       statusText: processed.rawText,
@@ -602,6 +601,10 @@ export function createTelegramPromptTurnRuntimeBuilder<
       admissionScope: deps.getAdmissionScope?.(),
       admissionJournalBinding: deps.getAdmissionJournalBinding?.(),
     });
+    return (historyTurns) => {
+      if (firstMessage) deps.assertExecutionCurrent?.(firstMessage);
+      return buildTurn(deps.allocateQueueOrder(), historyTurns);
+    };
   };
 }
 
@@ -670,9 +673,29 @@ function collectTelegramTurnAdmissionReceipts(
   return [...receipts.values()];
 }
 
-export async function buildTelegramPromptTurn(
+async function prepareTelegramPromptTurn(
+  options: Omit<BuildTelegramPromptTurnOptions, "queueOrder" | "historyTurns">,
+): Promise<(queueOrder: number, historyTurns: PendingTelegramTurn[]) => PendingTelegramTurn> {
+  const images: TelegramPromptContent[] = [];
+  for (const file of options.files) {
+    if (!file.isImage) continue;
+    const mediaType = file.mimeType || options.inferImageMimeType(file.path);
+    if (!mediaType) continue;
+    const buffer = await options.readBinaryFile(file.path);
+    images.push({
+      type: "image",
+      data: Buffer.from(buffer).toString("base64"),
+      mimeType: mediaType,
+    });
+  }
+  return (queueOrder, historyTurns) =>
+    buildPreparedTelegramPromptTurn({ ...options, queueOrder, historyTurns }, images);
+}
+
+function buildPreparedTelegramPromptTurn(
   options: BuildTelegramPromptTurnOptions,
-): Promise<PendingTelegramTurn> {
+  images: TelegramPromptContent[],
+): PendingTelegramTurn {
   const firstMessage = options.messages[0];
   if (!firstMessage) {
     throw new Error("Missing Telegram message for turn creation");
@@ -703,18 +726,8 @@ export async function buildTelegramPromptTurn(
         ),
       }),
     },
+    ...images,
   ];
-  for (const file of options.files) {
-    if (!file.isImage) continue;
-    const mediaType = file.mimeType || options.inferImageMimeType(file.path);
-    if (!mediaType) continue;
-    const buffer = await options.readBinaryFile(file.path);
-    content.push({
-      type: "image",
-      data: Buffer.from(buffer).toString("base64"),
-      mimeType: mediaType,
-    });
-  }
   if (options.voicePromptContribution?.trim()) {
     const textItem = content.find((c) => c.type === "text") as
       { type: "text"; text: string } | undefined;
@@ -759,6 +772,13 @@ export async function buildTelegramPromptTurn(
   };
 }
 
+export async function buildTelegramPromptTurn(
+  options: BuildTelegramPromptTurnOptions,
+): Promise<PendingTelegramTurn> {
+  const buildTurn = await prepareTelegramPromptTurn(options);
+  return buildTurn(options.queueOrder, options.historyTurns ?? []);
+}
+
 export async function buildTelegramPromptTurnRuntime(
   options: BuildTelegramPromptTurnRuntimeOptions,
 ): Promise<PendingTelegramTurn> {

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.10.6",
+  "version": "0.10.7",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -45,7 +45,7 @@
     "@llblab/pi-codex-usage": "0.9.4",
     "@llblab/pi-grow-loop": "0.8.1",
     "@llblab/pi-state-flow": "0.9.6",
-    "@llblab/pi-telegram": "0.45.6",
+    "@llblab/pi-telegram": "0.45.7",
     "@llblab/skills": "1.15.0"
   },
   "bundledDependencies": [