@llblab/pi-kit 0.27.6 → 0.28.0

package/node_modules/@llblab/pi-telegram/dist/lib/paths.js

@@ -3,13 +3,15 @@
  * Zones: telemetry paths, filesystem, runtime identity
  * Owns agent-dir detection and extension-local path derivation
  *
- * This domain is pure/path-only: it resolves directories and file paths
- * from environment and runtime identity. It does not read config, manage
- * state, or import broader Telegram domains.
+ * This domain is path-only: it resolves directories and file paths from
+ * environment and runtime identity. Its only filesystem read canonicalizes the
+ * existing agent-dir prefix; it does not read config, manage state, or import
+ * broader Telegram domains.
  */
 import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
 import { homedir } from "node:os";
-import { isAbsolute, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 export const TELEGRAM_DEFAULT_PROFILE_NAME = "default";
 /**
  * Resolve the agent data directory for the current Pi-compatible runtime.
@@ -50,11 +52,53 @@ export function requireTelegramStoragePathReference(path, expectedPath) {
 export function resolveTelegramConfigPath() {
     return join(resolveAgentDir(), "telegram.json");
 }
-/** Telegram bridge temporary directory (<agentDir>/tmp/telegram). */
+/**
+ * Resolve symlinks in the longest existing prefix of `path` and keep the missing suffix. Strict journal reads require
+ * canonical anchors, so a symlinked agent directory (for example macOS `/var` → `/private/var`) must not leak in.
+ * Relative input is returned unchanged so callers' exact-absolute-path guards still reject it. Windows keeps its
+ * spelling: strict journal reads are POSIX-only there, and resolving a drive-less root would add a drive letter.
+ */
+function canonicalizeExistingPrefix(path) {
+    if (!isAbsolute(path) || process.platform === "win32")
+        return path;
+    const absolute = resolve(path);
+    const missing = [];
+    for (let current = absolute;; current = dirname(current)) {
+        try {
+            return join(realpathSync(current), ...missing.reverse());
+        }
+        catch (error) {
+            if (error.code !== "ENOENT" || dirname(current) === current)
+                return absolute;
+            missing.push(basename(current));
+        }
+    }
+}
+/** Telegram bridge temporary directory (<agentDir>/tmp/pi-telegram); releases before 0.52.0 used `tmp/telegram`. */
 export function resolveTelegramTempDir(agentDir = resolveAgentDir()) {
-    return join(agentDir, "tmp", "telegram");
+    return join(canonicalizeExistingPrefix(agentDir), "tmp", "pi-telegram");
+}
+/** Consolidated-root service artifacts (transaction guards, staging and IPC), never session custody. */
+export function resolveTelegramRuntimeDir(agentDir = resolveAgentDir()) {
+    return join(resolveTelegramTempDir(agentDir), "runtime");
+}
+/** Rotated shared runtime event segments, outside the persistent root-file census. */
+export function resolveTelegramRuntimeLogsDir(agentDir = resolveAgentDir()) {
+    return join(resolveTelegramTempDir(agentDir), "logs");
+}
+/** Consolidated runtime state for every logical profile (`tmp/pi-telegram/state.json`). */
+export function resolveTelegramStatePath(agentDir = resolveAgentDir()) {
+    return join(resolveTelegramTempDir(agentDir), "state.json");
+}
+/** Flat attachment scratch directory (<agentDir>/tmp/pi-telegram/attachments). */
+export function resolveTelegramAttachmentsDir(agentDir = resolveAgentDir()) {
+    return join(resolveTelegramTempDir(agentDir), "attachments");
 }
-/** Telegram transport ownership store (<agentDir>/tmp/telegram/owners.json). */
+/** Read-only pre-0.52.0 ownership file, consulted only to refuse a second poller beside a live older leader. */
+export function resolveLegacyTelegramOwnersPath(agentDir = resolveAgentDir()) {
+    return join(agentDir, "tmp", "telegram", "owners.json");
+}
+/** Telegram transport ownership store (<agentDir>/tmp/pi-telegram/owners.json). */
 export function resolveTelegramOwnersPath() {
     return join(resolveTelegramTempDir(), "owners.json");
 }
@@ -66,15 +110,13 @@ export function getTelegramProfilePathSuffix(profileName) {
 export function resolveTelegramProfileTempFilePath(baseName, extension, agentDir = resolveAgentDir(), profileName) {
     return join(resolveTelegramTempDir(agentDir), `${baseName}${getTelegramProfilePathSuffix(profileName)}.${extension}`);
 }
-export function getTelegramDiagnosticsDisplayPaths(profileName) {
-    const suffix = getTelegramProfilePathSuffix(profileName);
-    const profileSlug = suffix.slice(1);
+export function getTelegramDiagnosticsDisplayPaths(_profileName) {
     return {
-        state: `~/.pi/agent/tmp/telegram/state${suffix}.json`,
-        logs: `~/.pi/agent/tmp/telegram/logs${profileSlug ? `.${profileSlug}` : ""}.jsonl`,
+        state: "~/.pi/agent/tmp/pi-telegram/state.json",
+        logs: "~/.pi/agent/tmp/pi-telegram/logs.jsonl",
     };
 }
-/** Durable Workspace admission ledger (<agentDir>/tmp/telegram/workspace-admission[.<profile>].json). */
+/** Durable Workspace admission ledger (<agentDir>/tmp/pi-telegram/workspace-admission[.<profile>].json). */
 export function resolveTelegramWorkspaceAdmissionPath(agentDir = resolveAgentDir(), profileName) {
     return resolveTelegramProfileTempFilePath("workspace-admission", "json", agentDir, profileName);
 }
@@ -82,6 +124,24 @@ export function resolveTelegramWorkspaceAdmissionPath(agentDir = resolveAgentDir
 export function resolveTelegramWorkspaceAdmissionPathForProfile(profileName) {
     return resolveTelegramWorkspaceAdmissionPath(resolveAgentDir(), profileName);
 }
+/** Consolidated non-session service journal (`journals/<kind>.<profile sha256>.json`) and its runtime namespace. */
+export function resolveTelegramServiceJournalStorage(kind, agentDir = resolveAgentDir(), profileName = TELEGRAM_DEFAULT_PROFILE_NAME) {
+    const profileHash = createHash("sha256").update(profileName).digest("hex");
+    return {
+        path: join(resolveTelegramTempDir(agentDir), "journals", `${kind}.${profileHash}.json`),
+        runtimeDir: resolveTelegramRuntimeDir(agentDir),
+    };
+}
+/** Bind one non-session journal to its exact colocated-root service namespace, never a format fallback. */
+export function getTelegramJournalPublicationPaths(path, runtimeDir) {
+    if (runtimeDir === undefined)
+        return { transactionPath: `${path}.transaction`, temporaryBasePath: path };
+    requireTelegramStoragePathReference(path, resolve(path));
+    requireTelegramStoragePathReference(runtimeDir, join(dirname(dirname(path)), "runtime"));
+    if (basename(dirname(path)) !== "journals")
+        throw new Error("Telegram service journal must use its journals namespace.");
+    return { transactionPath: join(runtimeDir, `${basename(path)}.transaction`), temporaryBasePath: join(runtimeDir, basename(path)) };
+}
 /** Durable inactive Thread cleanup work-set journal. */
 export function resolveTelegramThreadCleanupWorkPath(agentDir = resolveAgentDir(), profileName) {
     return resolveTelegramProfileTempFilePath("thread-cleanup", "json", agentDir, profileName);
@@ -90,7 +150,7 @@ export function resolveTelegramThreadCleanupWorkPath(agentDir = resolveAgentDir(
 export function resolveTelegramChannelPostJournalPath(agentDir = resolveAgentDir(), profileName) {
     return resolveTelegramProfileTempFilePath("channel-posts", "json", agentDir, profileName);
 }
-/** Durable inbound update journal (<agentDir>/tmp/telegram/inbox[.<profile>].json). */
+/** Durable inbound update journal (<agentDir>/tmp/pi-telegram/inbox[.<profile>].json). */
 export function resolveTelegramUpdateJournalPath(agentDir = resolveAgentDir(), profileName) {
     return resolveTelegramProfileTempFilePath("inbox", "json", agentDir, profileName);
 }
@@ -109,7 +169,85 @@ export function resolveTelegramFollowerJournalPath(recipientBindingKey, agentDir
         .slice(0, 16);
     return resolveTelegramProfileTempFilePath(`follower-inbox-${bindingHash}`, "json", agentDir, profileName);
 }
-/** Runtime event log (<agentDir>/tmp/telegram/logs.jsonl). */
-export function resolveTelegramRuntimeLogPath() {
-    return resolveTelegramProfileTempFilePath("logs", "jsonl");
+const TELEGRAM_SESSION_DIRECTORY_MAX_LENGTH = 200;
+const WINDOWS_RESERVED_NAME = /^(?:con|prn|aux|nul|com[0-9]|lpt[0-9])(?:\..*)?$/u;
+/**
+ * Directory name for a session id. Lowercase letters, digits, `_`, `-` and inner `.` stay verbatim, so every real
+ * (UUID-shaped) id is unchanged; any other UTF-8 byte is percent-encoded. Uppercase is encoded so case-insensitive
+ * filesystems never merge two sessions; a leading or trailing dot and Windows reserved names are encoded so the name
+ * can never be `.`/`..`, hidden, or a device. The encoding is reversible; an empty or over-long result is refused.
+ */
+export function encodeTelegramSessionDirectoryName(sessionId) {
+    if (typeof sessionId !== "string" || sessionId.length === 0)
+        return undefined;
+    const bytes = Buffer.from(sessionId, "utf8");
+    if (bytes.toString("utf8") !== sessionId)
+        return undefined;
+    let name = "";
+    bytes.forEach((byte, index) => {
+        const char = String.fromCharCode(byte);
+        const safe = /[a-z0-9_-]/u.test(char) || (char === "." && index > 0 && index < bytes.length - 1);
+        name += safe ? char : `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+    });
+    if (WINDOWS_RESERVED_NAME.test(name))
+        name = `%${name.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}${name.slice(1)}`;
+    return name.length <= TELEGRAM_SESSION_DIRECTORY_MAX_LENGTH ? name : undefined;
+}
+/** Inverse of `encodeTelegramSessionDirectoryName`; undefined unless the name is exactly canonical. */
+export function decodeTelegramSessionDirectoryName(name) {
+    if (!/^[a-z0-9_.%A-F-]+$/u.test(name))
+        return undefined;
+    const bytes = [];
+    for (let index = 0; index < name.length; index++) {
+        if (name[index] === "%") {
+            const hex = name.slice(index + 1, index + 3);
+            if (!/^[0-9A-F]{2}$/u.test(hex))
+                return undefined;
+            bytes.push(Number.parseInt(hex, 16));
+            index += 2;
+        }
+        else
+            bytes.push(name.charCodeAt(index));
+    }
+    const decoded = Buffer.from(bytes).toString("utf8");
+    return encodeTelegramSessionDirectoryName(decoded) === name ? decoded : undefined;
+}
+/** Root of every session folder (<agentDir>/tmp/pi-telegram/sessions). */
+export function resolveTelegramSessionsDir(agentDir = resolveAgentDir()) {
+    return join(resolveTelegramTempDir(agentDir), "sessions");
+}
+/** One session's folder (<agentDir>/tmp/pi-telegram/sessions/<session id>). */
+export function resolveTelegramSessionDir(sessionId, agentDir = resolveAgentDir()) {
+    const name = encodeTelegramSessionDirectoryName(sessionId);
+    if (!name)
+        throw new Error("Telegram session directory requires a usable session id.");
+    return join(resolveTelegramSessionsDir(agentDir), name);
+}
+/** Hash naming one recipient incarnation inside its session folder; unchanged from the former follower inbox. */
+export function getTelegramRecipientJournalHash(recipientBindingKey) {
+    if (!recipientBindingKey)
+        throw new Error("Telegram session journal binding key is required.");
+    return createHash("sha256").update(recipientBindingKey).digest("hex").slice(0, 16);
+}
+/** Durable per-session journal (`sessions/<session id>/journal.<hash>[.<profile>].json`); the name never reveals a role. */
+export function resolveTelegramSessionJournalPath(sessionId, recipientBindingKey, agentDir = resolveAgentDir(), profileName) {
+    return join(resolveTelegramSessionDir(sessionId, agentDir), `journal.${getTelegramRecipientJournalHash(recipientBindingKey)}${getTelegramProfilePathSuffix(profileName)}.json`);
+}
+/** Leader polling journal hosted by the session that first led (`sessions/<id>/inbox[.<profile>].json`); owners.json names it. */
+export function resolveTelegramSessionPollingJournalPath(sessionId, agentDir = resolveAgentDir(), profileName) {
+    return join(resolveTelegramSessionDir(sessionId, agentDir), `inbox${getTelegramProfilePathSuffix(profileName)}.json`);
+}
+/** Accept only a canonical `sessions/<id>/inbox[.<profile>].json` beneath this agent's runtime. */
+export function isTelegramSessionPollingJournalPath(path, agentDir = resolveAgentDir()) {
+    const parts = relative(resolveTelegramSessionsDir(agentDir), path).split(sep);
+    return isAbsolute(path) && parts.length === 2 && decodeTelegramSessionDirectoryName(parts[0]) !== undefined &&
+        /^inbox(?:\.[a-zA-Z0-9._-]+)?\.json$/u.test(parts[1]);
+}
+/** Runtime event log (<agentDir>/tmp/pi-telegram/logs.jsonl). */
+export function resolveTelegramRuntimeLogPath(agentDir = resolveAgentDir()) {
+    return resolveTelegramProfileTempFilePath("logs", "jsonl", agentDir);
+}
+/** Bounded previous shared log segment below `logs/`. */
+export function resolveTelegramPreviousSharedRuntimeLogPath(agentDir = resolveAgentDir()) {
+    return join(resolveTelegramRuntimeLogsDir(agentDir), "logs._prev.jsonl");
 }

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

@@ -68,6 +68,7 @@ export declare function createScopedModelPatternPersister(deps: {
 export declare function getExtensionContextModel(ctx: ExtensionContext): ExtensionContext["model"];
 export declare function getExtensionContextCwd(ctx: ExtensionContext): string;
 export declare function getExtensionContextSessionId(ctx: ExtensionContext): string;
+export declare function getExtensionContextSessionId(ctx: ExtensionContext | undefined): string | undefined;
 export declare function isExtensionContextIdle(ctx: ExtensionContext): boolean;
 export declare function hasExtensionContextPendingMessages(ctx: ExtensionContext): boolean;
 export declare function compactExtensionContext(ctx: ExtensionContext, callbacks: Parameters<ExtensionContext["compact"]>[0]): ReturnType<ExtensionContext["compact"]>;

package/node_modules/@llblab/pi-telegram/dist/lib/pi.js

@@ -109,7 +109,8 @@ export function getExtensionContextCwd(ctx) {
     return ctx.cwd;
 }
 export function getExtensionContextSessionId(ctx) {
-    return ctx.sessionManager.getSessionId();
+    // Minimal hosts and stale contexts may omit a session manager; absence is not an invented ID.
+    return ctx?.sessionManager?.getSessionId?.();
 }
 export function isExtensionContextIdle(ctx) {
     return ctx.isIdle();

package/node_modules/@llblab/pi-telegram/dist/lib/polling.d.ts

@@ -11,7 +11,6 @@ export interface TelegramUpdate {
     update_id: number;
 }
 export declare const TELEGRAM_GET_UPDATES_CONFLICT_STOP_LIMIT = 10;
-export declare const TELEGRAM_GET_UPDATES_GRACE_MS = 10000;
 export declare const TELEGRAM_ALLOWED_UPDATES: readonly ["message", "edited_message", "callback_query", "message_reaction", "guest_message"];
 export declare function buildTelegramInitialSyncRequest(): {
     offset: number;
@@ -57,7 +56,6 @@ export interface TelegramPollingControllerState extends TelegramPollingStateSnap
     pollingController?: AbortController;
 }
 export declare function createTelegramPollingControllerState(): TelegramPollingControllerState;
-export declare function getTelegramPollingStateSnapshot(state: TelegramPollingControllerState): TelegramPollingStateSnapshot;
 export declare function createTelegramPollingStateReader(state: TelegramPollingControllerState): () => TelegramPollingStateSnapshot;
 export declare function isTelegramPollingControllerActive(state: TelegramPollingControllerState): boolean;
 export declare function createTelegramPollingActivityReader(state: TelegramPollingControllerState): () => boolean;
@@ -271,11 +269,8 @@ export interface TelegramThreadCapabilityOrchestration<TContext, TOwner> {
 }
 export declare function createTelegramThreadCapabilityStateRuntime(): TelegramThreadCapabilityStateRuntime;
 export declare function createTelegramThreadCapabilityOrchestration<TContext, TOwner>(deps: TelegramThreadCapabilityOrchestrationDeps<TContext, TOwner>): TelegramThreadCapabilityOrchestration<TContext, TOwner>;
-export declare function readTelegramThreadCapability(deps: TelegramThreadCapabilityReaderDeps): Promise<boolean | undefined>;
-export declare function probeTelegramStartupThreadCapability(deps: TelegramStartupThreadCapabilityProbeDeps, isCurrent?: () => boolean): Promise<boolean | undefined>;
 export declare function applyTelegramThreadCapability<TContext>(ctx: TContext, threadModeEnabled: boolean, phase: string, deps: TelegramThreadCapabilityRuntimeDeps<TContext>, isCurrent?: () => boolean): Promise<void>;
 export declare function createTelegramThreadAwarePollingPorts<TContext, TOwner>(deps: TelegramThreadAwarePollingDeps<TContext, TOwner>): TelegramThreadAwarePollingPorts<TContext, TOwner>;
-export declare function createTelegramThreadTargetObservationHandler<TContext>(deps: TelegramThreadCapabilityRuntimeDeps<TContext>): TelegramThreadTargetObservationHandler<TContext>;
 export declare function canProbeTelegramThreadCapability<TContext>(ctx: TContext, deps: Pick<TelegramThreadCapabilityRuntimeDeps<TContext>, "ownsLock" | "isFollowerRegistered">): boolean;
 export declare function createTelegramThreadCapabilityMonitor<TContext>(deps: TelegramThreadCapabilityRuntimeDeps<TContext>): TelegramThreadCapabilityMonitor<TContext>;
 export declare class TelegramPollingBatchValidationError extends Error {

package/node_modules/@llblab/pi-telegram/dist/lib/polling.js

@@ -15,7 +15,7 @@ const TELEGRAM_GET_UPDATES_CONFLICT_FAST_RETRY_LIMIT = 3;
 const TELEGRAM_GET_UPDATES_CONFLICT_FAST_RETRY_MS = 1_000;
 const TELEGRAM_GET_UPDATES_CONFLICT_SLOW_RETRY_MS = 3_000;
 const TELEGRAM_POLLING_RETRY_MS = 3_000;
-export const TELEGRAM_GET_UPDATES_GRACE_MS = 10_000;
+const TELEGRAM_GET_UPDATES_GRACE_MS = 10_000;
 // Standard Telegram DM polling does not expose ordinary message-deletion events.
 // Business deletions belong to a separate namespace and default routing ignores them.
 export const TELEGRAM_ALLOWED_UPDATES = [
@@ -80,7 +80,7 @@ export function createTelegramPollingControllerState() {
         stopReason: "not-started",
     };
 }
-export function getTelegramPollingStateSnapshot(state) {
+function getTelegramPollingStateSnapshot(state) {
     return {
         phase: state.phase,
         phaseStartedAtMs: state.phaseStartedAtMs,
@@ -481,7 +481,7 @@ export function createTelegramThreadCapabilityOrchestration(deps) {
         }),
     };
 }
-export async function readTelegramThreadCapability(deps) {
+async function readTelegramThreadCapability(deps) {
     const bot = await deps.callApi("getMe", {});
     if (bot.has_topics_enabled === true)
         return true;
@@ -489,7 +489,7 @@ export async function readTelegramThreadCapability(deps) {
         return false;
     return undefined;
 }
-export async function probeTelegramStartupThreadCapability(deps, isCurrent = () => true) {
+async function probeTelegramStartupThreadCapability(deps, isCurrent = () => true) {
     if (!isCurrent())
         return;
     const threadModeEnabled = await readTelegramThreadCapability(deps);
@@ -770,7 +770,7 @@ export function createTelegramThreadAwarePollingPorts(deps) {
         stopFollowerRegistration: deps.stopFollowerRegistration,
     };
 }
-export function createTelegramThreadTargetObservationHandler(deps) {
+function createTelegramThreadTargetObservationHandler(deps) {
     let transitionPending = false;
     return async (ctx) => {
         if (transitionPending)

package/node_modules/@llblab/pi-telegram/dist/lib/preview.d.ts

@@ -156,7 +156,6 @@ export declare function createTelegramNativeMarkdownPreviewFinalizer<TReplyMarku
 }) => Promise<boolean>;
 export declare function createTelegramAssistantPreviewRuntime<TMessage, TReplyMarkup = TelegramPreviewReplyMarkup>(deps: TelegramAssistantPreviewRuntimeDeps<TMessage, TReplyMarkup>): TelegramAssistantPreviewRuntime<TMessage, TReplyMarkup>;
 export declare function createTelegramPreviewController(deps: TelegramPreviewControllerDeps): TelegramPreviewController;
-export declare function createTelegramAssistantMessagePreviewHooks<TMessage>(deps: TelegramAssistantMessagePreviewHookDeps<TMessage>): TelegramAssistantMessagePreviewHooks<TMessage>;
 /**
  * Returns true when the active turn is a Telegram Guest Mode query. A guest
  * query allows exactly one answer within a limited Telegram response window,
@@ -165,8 +164,6 @@ export declare function createTelegramAssistantMessagePreviewHooks<TMessage>(dep
 export declare function shouldSuppressPreviewForGuestTurn(turn: {
     guestQueryId?: string;
 } | null | undefined): boolean;
-export declare function handleTelegramAssistantMessagePreviewStart<TMessage>(message: TMessage, deps: TelegramAssistantMessagePreviewStartDeps<TMessage>): Promise<void>;
-export declare function handleTelegramAssistantMessagePreviewUpdate<TMessage>(message: TMessage, deps: TelegramAssistantMessagePreviewUpdateDeps<TMessage>): Promise<void>;
 export declare function buildTelegramPreviewFinalText(state: TelegramPreviewState): string | undefined;
 export declare function createTelegramPreviewRuntimeState(): TelegramPreviewRuntimeState;
 export declare function allocateTelegramDraftId(currentDraftId: number, maxDraftId: number): number;

package/node_modules/@llblab/pi-telegram/dist/lib/preview.js

@@ -168,7 +168,7 @@ export function createTelegramPreviewController(deps) {
         finalize: (chatId, _replyToMessageId, options) => finalizeTelegramPreview(chatId, getRuntimeDeps(), options),
     };
 }
-export function createTelegramAssistantMessagePreviewHooks(deps) {
+function createTelegramAssistantMessagePreviewHooks(deps) {
     return {
         onMessageStart: async (event) => {
             await handleTelegramAssistantMessagePreviewStart(event.message, deps);
@@ -186,7 +186,7 @@ export function createTelegramAssistantMessagePreviewHooks(deps) {
 export function shouldSuppressPreviewForGuestTurn(turn) {
     return !!turn?.guestQueryId;
 }
-export async function handleTelegramAssistantMessagePreviewStart(message, deps) {
+async function handleTelegramAssistantMessagePreviewStart(message, deps) {
     const turn = deps.getActiveTurn();
     if (!turn || !deps.isAssistantMessage(message))
         return;
@@ -211,7 +211,7 @@ export async function handleTelegramAssistantMessagePreviewStart(message, deps)
     next.precedingFlush = state?.publicationPromise ?? state?.flushPromise ?? state?.precedingFlush;
     deps.setState(next);
 }
-export async function handleTelegramAssistantMessagePreviewUpdate(message, deps) {
+async function handleTelegramAssistantMessagePreviewUpdate(message, deps) {
     const turn = deps.getActiveTurn();
     if (!turn || !deps.isAssistantMessage(message))
         return;

package/node_modules/@llblab/pi-telegram/dist/lib/prompt-templates.d.ts

@@ -12,7 +12,6 @@ export interface TelegramPromptTemplateCommand {
 export type TelegramPromptTemplateReader = (path: string) => string;
 export declare function parsePromptTemplateArgs(argsString: string): string[];
 export declare function substitutePromptTemplateArgs(content: string, args: readonly string[]): string;
-export declare function isTelegramPromptTemplateCommandName(name: string): boolean;
 export declare function mapPiPromptTemplateNameToTelegramCommandName(name: string): string | undefined;
 export interface TelegramPromptTemplateCommandGetterDeps {
     getCommands: () => readonly PiSlashCommandInfo[];

package/node_modules/@llblab/pi-telegram/dist/lib/prompt-templates.js

@@ -63,7 +63,7 @@ export function substitutePromptTemplateArgs(content, args) {
     const allArgs = args.join(" ");
     return result.replace(/\$ARGUMENTS/g, allArgs).replace(/\$@/g, allArgs);
 }
-export function isTelegramPromptTemplateCommandName(name) {
+function isTelegramPromptTemplateCommandName(name) {
     return TELEGRAM_BOT_COMMAND_NAME_PATTERN.test(name);
 }
 export function mapPiPromptTemplateNameToTelegramCommandName(name) {

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

@@ -98,7 +98,6 @@ export interface PendingTelegramControlItem<TContext = unknown> extends Telegram
 }
 export type TelegramQueueItem<TContext = unknown> = PendingTelegramTurn | PendingTelegramControlItem<TContext>;
 export declare const TELEGRAM_QUEUE_HANDOFF_PAYLOAD_MAX_BYTES: number;
-export declare const TELEGRAM_QUEUE_HANDOFF_MAX_RECEIPTS = 256;
 export interface TelegramQueueHandoffBase {
     chatId: number;
     target?: TelegramQueueTarget;
@@ -132,6 +131,8 @@ export interface TelegramQueueHandoff {
     handoffToken: string;
     payload: TelegramQueueHandoffPayload;
 }
+/** Data decoder shared by authenticated IPC and cold storage; decoding grants no admission. */
+export declare function parseTelegramQueueHandoffPayload(value: unknown): TelegramQueueHandoffPayload | undefined;
 export interface TelegramQueueHandoffStageReceipt {
     status: "staged";
     receiptId: string;
@@ -192,14 +193,12 @@ export declare function getTelegramQueueLaneContract(lane: TelegramQueueLane): T
 export declare function getTelegramQueueItemAdmissionMode(item: Pick<TelegramQueueItem, "queueLane">): TelegramQueueAdmissionMode;
 export declare function isTelegramQueueItemAdmissionValid(item: Pick<TelegramQueueItem, "kind" | "queueLane">): boolean;
 export declare function assertTelegramQueueItemAdmissionValid(item: Pick<TelegramQueueItem, "kind" | "queueLane" | "admissionReceipts">): void;
-export declare function isPendingTelegramTurn<TContext = unknown>(item: TelegramQueueItem<TContext>): item is PendingTelegramTurn;
 export declare function createTelegramQueueStore<TContext = unknown>(initialItems?: TelegramQueueItem<TContext>[]): TelegramQueueStateStore<TContext>;
 export declare function createTelegramTransportStampRuntime(deps: {
     getProfileName(): string | undefined;
     getBotToken(): string | undefined;
 }): TelegramTransportStampRuntime;
 export declare function createTelegramTransportStampedQueueStore<TContext>(store: TelegramQueueStateStore<TContext>, getTransportStamp: () => TelegramTransportStamp): TelegramQueueStateStore<TContext>;
-export declare function isTelegramQueueItemSkipped<TContext = unknown>(item: TelegramQueueItem<TContext>): boolean;
 export declare function countExecutableTelegramQueueItems<TContext = unknown>(items: readonly TelegramQueueItem<TContext>[]): number;
 export declare function createTelegramQueueItemCountGetter<TContext = unknown>(store: Pick<TelegramQueueStore<TContext>, "getQueuedItems">): () => number;
 export declare function createTelegramActiveTurnStore<TTurn extends PendingTelegramTurn = PendingTelegramTurn>(): TelegramActiveTurnStore<TTurn>;
@@ -246,11 +245,6 @@ export declare function removeTelegramQueueItemsByMessageIds<TContext = unknown>
     removedItems: TelegramQueueItem<TContext>[];
     removedCount: number;
 };
-export declare function removeTelegramQueuedGuestPromptByOrder<TContext = unknown>(items: TelegramQueueItem<TContext>[], queueOrder: number): {
-    items: TelegramQueueItem<TContext>[];
-    removedItems: PendingTelegramTurn[];
-    removedCount: number;
-};
 export declare function applyTelegramQueuePromptReactionDisposition<TContext = unknown>(items: TelegramQueueItem<TContext>[], messageId: number, disposition: TelegramQueueReactionDisposition, destinationLaneOrder?: number, scope?: TelegramQueueMessageScope): {
     items: TelegramQueueItem<TContext>[];
     changed: boolean;
@@ -680,10 +674,8 @@ export declare function createTelegramSessionLifecycleHooks<TContext, TQueueItem
     onSessionShutdown: (_event?: TelegramSessionLifecycleHookEvent, ctx?: TContext) => Promise<void>;
 };
 export declare function createTelegramQueueMutationController<TContext>(deps: TelegramQueueMutationControllerDeps<TContext>): TelegramQueueMutationController<TContext>;
-export declare function reorderTelegramQueueItemsRuntime<TContext>(deps: TelegramQueueMutationRuntimeDeps<TContext>): void;
 export declare function clearTelegramQueueItemsRuntime<TContext>(deps: TelegramQueueMutationRuntimeDeps<TContext>): number;
 export declare function removeTelegramQueueItemsByMessageIdsRuntime<TContext>(messageIds: number[], deps: TelegramQueueMutationRuntimeDeps<TContext>, scope?: TelegramQueueMessageScope): number;
-export declare function removeTelegramQueuedGuestPromptByOrderRuntime<TContext>(queueOrder: number, deps: TelegramQueueMutationRuntimeDeps<TContext>): boolean;
 export declare function applyTelegramQueuePromptReactionDispositionRuntime<TContext>(messageId: number, disposition: TelegramQueueReactionDisposition, deps: TelegramQueueMutationRuntimeDeps<TContext>, scope?: TelegramQueueMessageScope): boolean;
 export declare function enqueueTelegramPromptTurnRuntime<TMessage, TContext = unknown>(messages: TMessage[], deps: TelegramPromptEnqueueRuntimeDeps<TMessage, TContext>): Promise<PendingTelegramTurn>;
 export declare function createTelegramPromptEnqueueController<TMessage, TContext = unknown>(deps: TelegramPromptEnqueueControllerDeps<TMessage, TContext>): TelegramPromptEnqueueController<TMessage, TContext>;
@@ -695,6 +687,7 @@ export interface TelegramControlRuntimeDeps<TContext> extends TelegramRuntimeEve
     ctx: TContext;
     sendTextReply: (chatId: number, replyToMessageId: number, text: string, options?: {
         target?: TelegramQueueTarget;
+        parseMode?: "HTML";
     }) => Promise<number | undefined>;
     onSettled: (item: PendingTelegramControlItem<TContext>) => void;
 }
@@ -712,11 +705,6 @@ export interface TelegramDeferredQueueDispatchRuntime<TContext = unknown> {
     isGenerationActive: (generation: number) => boolean;
     request: (dispatchNextQueuedTelegramTurn: (ctx: TContext) => void) => void;
 }
-/**
- * Production debounce for deferred queue dispatch; the factory defaults to this
- * so the entrypoint wires ports instead of policy constants.
- */
-export declare const TELEGRAM_DEFERRED_DISPATCH_DELAY_MS = 50;
 export declare function createTelegramDeferredQueueDispatchRuntime<TContext = unknown>(deps?: TelegramDeferredQueueDispatchRuntimeDeps): TelegramDeferredQueueDispatchRuntime<TContext>;
 export interface TelegramQueueDispatchWatchdogRuntime<TContext = unknown> {
     start: (ctx: TContext) => void;

package/node_modules/@llblab/pi-telegram/dist/lib/queue.js

@@ -5,6 +5,7 @@
  */
 import { createHash } from "node:crypto";
 import { isVoiceTurn } from "./voice.js";
+import { isWireRecord as isQueuePayloadRecord } from "./wire.js";
 import { isTelegramApiCommitUnknownError } from "./telegram-api.js";
 export const TELEGRAM_QUEUE_LANE_CONTRACTS = [
     // Control lane intentionally accepts both direct controls and resume prompts.
@@ -30,7 +31,67 @@ export const TELEGRAM_QUEUE_LANE_CONTRACTS = [
     },
 ];
 export const TELEGRAM_QUEUE_HANDOFF_PAYLOAD_MAX_BYTES = 8 * 1024 * 1024;
-export const TELEGRAM_QUEUE_HANDOFF_MAX_RECEIPTS = 256;
+const TELEGRAM_QUEUE_HANDOFF_MAX_RECEIPTS = 256;
+function parseQueuePayloadReceipt(value, kind) {
+    if (!isQueuePayloadRecord(value) || value.queueKind !== kind ||
+        typeof value.receiptId !== "string" || !value.receiptId ||
+        (value.journalBindingKey !== undefined && (typeof value.journalBindingKey !== "string" || !value.journalBindingKey.trim())) ||
+        !Array.isArray(value.sourceUpdateIds) || value.sourceUpdateIds.length === 0 ||
+        value.sourceUpdateIds.some((id, index) => !Number.isSafeInteger(id) || id < 0 ||
+            (index > 0 && id <= value.sourceUpdateIds[index - 1])))
+        return undefined;
+    return { queueKind: kind, receiptId: value.receiptId, sourceUpdateIds: value.sourceUpdateIds,
+        ...(typeof value.journalBindingKey === "string" ? { journalBindingKey: value.journalBindingKey } : {}) };
+}
+/** Data decoder shared by authenticated IPC and cold storage; decoding grants no admission. */
+export function parseTelegramQueueHandoffPayload(value) {
+    if (!isQueuePayloadRecord(value) || (value.kind !== "prompt" && value.kind !== "control"))
+        return undefined;
+    const target = isQueuePayloadRecord(value.target) && typeof value.target.chatId === "number"
+        ? { chatId: value.target.chatId, ...(typeof value.target.threadId === "number" ? { threadId: value.target.threadId } : {}) } : undefined;
+    const transportStamp = isQueuePayloadRecord(value.transportStamp) &&
+        typeof value.transportStamp.profile === "string" && typeof value.transportStamp.generation === "string"
+        ? { profile: value.transportStamp.profile, generation: value.transportStamp.generation } : undefined;
+    if (!Number.isSafeInteger(value.chatId) || (value.target !== undefined && !target) ||
+        (value.transportStamp !== undefined && !transportStamp) || !Number.isSafeInteger(value.replyToMessageId) ||
+        (value.guestQueryId !== undefined && typeof value.guestQueryId !== "string") ||
+        (value.guestInlineMessageId !== undefined && typeof value.guestInlineMessageId !== "string") ||
+        !Number.isSafeInteger(value.queueOrder) || (value.queueLane !== "control" && value.queueLane !== "priority" && value.queueLane !== "default") ||
+        !Number.isSafeInteger(value.laneOrder) || typeof value.statusSummary !== "string" || !Array.isArray(value.admissionReceipts))
+        return undefined;
+    const admissionReceipts = value.admissionReceipts.map(receipt => parseQueuePayloadReceipt(receipt, value.kind));
+    if (admissionReceipts.length === 0 || admissionReceipts.length > TELEGRAM_QUEUE_HANDOFF_MAX_RECEIPTS ||
+        admissionReceipts.some(receipt => !receipt))
+        return undefined;
+    const base = { chatId: value.chatId, ...(target ? { target } : {}), ...(transportStamp ? { transportStamp } : {}),
+        replyToMessageId: value.replyToMessageId,
+        ...(typeof value.guestQueryId === "string" ? { guestQueryId: value.guestQueryId } : {}),
+        ...(typeof value.guestInlineMessageId === "string" ? { guestInlineMessageId: value.guestInlineMessageId } : {}),
+        queueOrder: value.queueOrder, queueLane: value.queueLane,
+        laneOrder: value.laneOrder, statusSummary: value.statusSummary,
+        admissionReceipts: admissionReceipts };
+    if (value.kind === "control") {
+        return value.queueLane === "control" && (value.controlType === "status" || value.controlType === "model")
+            ? { kind: "control", controlType: value.controlType, ...base } : undefined;
+    }
+    if (value.queueLane === "control" || !Array.isArray(value.sourceMessageIds) || value.sourceMessageIds.some(id => !Number.isSafeInteger(id)) ||
+        !Array.isArray(value.queuedAttachments) || value.queuedAttachments.some(attachment => !isQueuePayloadRecord(attachment) ||
+        typeof attachment.path !== "string" || typeof attachment.fileName !== "string") ||
+        !Array.isArray(value.content) || value.content.some(content => !isQueuePayloadRecord(content) ||
+        (content.type === "text" ? typeof content.text !== "string" : content.type === "image"
+            ? typeof content.data !== "string" || typeof content.mimeType !== "string" : true)) ||
+        typeof value.historyText !== "string" || (value.priorityEmoji !== undefined && typeof value.priorityEmoji !== "string") ||
+        (value.reactionSuppressionEmoji !== undefined && typeof value.reactionSuppressionEmoji !== "string") ||
+        (value.voiceReplyPreferred !== undefined && typeof value.voiceReplyPreferred !== "boolean") ||
+        (value.voiceReplyRequired !== undefined && typeof value.voiceReplyRequired !== "boolean"))
+        return undefined;
+    return { kind: "prompt", ...base, sourceMessageIds: value.sourceMessageIds,
+        queuedAttachments: value.queuedAttachments, content: value.content, historyText: value.historyText,
+        ...(typeof value.priorityEmoji === "string" ? { priorityEmoji: value.priorityEmoji } : {}),
+        ...(typeof value.reactionSuppressionEmoji === "string" ? { reactionSuppressionEmoji: value.reactionSuppressionEmoji } : {}),
+        ...(typeof value.voiceReplyPreferred === "boolean" ? { voiceReplyPreferred: value.voiceReplyPreferred } : {}),
+        ...(typeof value.voiceReplyRequired === "boolean" ? { voiceReplyRequired: value.voiceReplyRequired } : {}) };
+}
 export function createTelegramQueueAdmissionReceipt(options) {
     if (options.sourceUpdateIds.length === 0)
         return undefined;
@@ -100,7 +161,7 @@ export function assertTelegramQueueItemAdmissionValid(item) {
 function getTelegramQueueLaneRank(lane) {
     return getTelegramQueueLaneContract(lane).dispatchRank;
 }
-export function isPendingTelegramTurn(item) {
+function isPendingTelegramTurn(item) {
     return item.kind === "prompt";
 }
 export function createTelegramQueueStore(initialItems = []) {
@@ -148,7 +209,7 @@ export function createTelegramTransportStampedQueueStore(store, getTransportStam
         },
     };
 }
-export function isTelegramQueueItemSkipped(item) {
+function isTelegramQueueItemSkipped(item) {
     return item.kind === "prompt" && Boolean(item.reactionSuppressionEmoji);
 }
 export function countExecutableTelegramQueueItems(items) {
@@ -503,7 +564,7 @@ export function removeTelegramQueueItemsByMessageIds(items, messageIds, scope) {
         removedCount: removedItems.length,
     };
 }
-export function removeTelegramQueuedGuestPromptByOrder(items, queueOrder) {
+function removeTelegramQueuedGuestPromptByOrder(items, queueOrder) {
     const index = items.findIndex((item) => {
         return isPendingTelegramTurn(item) &&
             item.guestQueryId !== undefined &&
@@ -1499,7 +1560,7 @@ function appendTelegramQueueItemRuntime(item, deps) {
         return;
     commitReorderedTelegramQueueItemsRuntime(nextItems, deps);
 }
-export function reorderTelegramQueueItemsRuntime(deps) {
+function reorderTelegramQueueItemsRuntime(deps) {
     commitReorderedTelegramQueueItemsRuntime(deps.getQueuedItems(), deps);
 }
 export function clearTelegramQueueItemsRuntime(deps) {
@@ -1528,7 +1589,7 @@ export function removeTelegramQueueItemsByMessageIdsRuntime(messageIds, deps, sc
     updateTelegramQueueStatusRuntime(deps);
     return removedCount;
 }
-export function removeTelegramQueuedGuestPromptByOrderRuntime(queueOrder, deps) {
+function removeTelegramQueuedGuestPromptByOrderRuntime(queueOrder, deps) {
     const { items, removedItems, removedCount } = removeTelegramQueuedGuestPromptByOrder(deps.getQueuedItems(), queueOrder);
     if (removedCount === 0)
         return false;
@@ -1639,7 +1700,7 @@ export async function executeTelegramControlItemRuntime(item, deps) {
  * Production debounce for deferred queue dispatch; the factory defaults to this
  * so the entrypoint wires ports instead of policy constants.
  */
-export const TELEGRAM_DEFERRED_DISPATCH_DELAY_MS = 50;
+const TELEGRAM_DEFERRED_DISPATCH_DELAY_MS = 50;
 export function createTelegramDeferredQueueDispatchRuntime(deps = {}) {
     let boundContext;
     let generation = 0;
@@ -2004,7 +2065,7 @@ export function createTelegramQueueDispatchController(deps) {
                 const announcementGeneration = nextDispatchAnnouncementGeneration;
                 const dispatchGeneration = deps.getDispatchGeneration?.();
                 deps.updateStatus(ctx);
-                void deps.sendTextReply(dispatchPlan.item.chatId, dispatchPlan.item.replyToMessageId, "<b>⏩ Dispatching next queued turn.</b>", { target: dispatchPlan.item.target }).catch((error) => {
+                void deps.sendTextReply(dispatchPlan.item.chatId, dispatchPlan.item.replyToMessageId, "<b>⏩ Dispatching next queued turn.</b>", { target: dispatchPlan.item.target, parseMode: "HTML" }).catch((error) => {
                     deps.recordRuntimeEvent?.("dispatch", error, {
                         phase: "next-announcement",
                     });