@llblab/pi-kit 0.27.6 → 0.28.0

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

@@ -8,12 +8,18 @@ import { chmodSync, closeSync, constants, createReadStream, fstatSync, lstatSync
   readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { lstat } from "node:fs/promises";
 import { basename, dirname } from "node:path";
+import { getTelegramJournalPublicationPaths } from "./paths.ts";
 import { createHash, randomUUID } from "node:crypto";
 
 import { Type } from "@sinclair/typebox";
 
 import { renameTelegramPathWithRetry, withTelegramFileTransaction } from "./locks.ts";
 import type { ExtensionAPI } from "./pi.ts";
+import {
+  isWireRecord as isRecord,
+  hasOnlyWireKeys as hasOnlyKeys,
+  isNonNegativeWireInteger as isSafeTime,
+} from "./wire.ts";
 
 const CHANNEL_POST_JOURNAL_VERSION = 1;
 const DEFAULT_MAX_RECORDS = 256;
@@ -31,12 +37,12 @@ export interface TelegramChannelPostMediaIntent {
   sha256: string;
 }
 
-export const TELEGRAM_CHANNEL_POST_MEDIA_MAX_BYTES: Record<TelegramChannelPostMediaKind, number> = {
+const TELEGRAM_CHANNEL_POST_MEDIA_MAX_BYTES: Record<TelegramChannelPostMediaKind, number> = {
   photo: 10 * 1024 * 1024,
   video: 50 * 1024 * 1024,
 };
-export const TELEGRAM_CHANNEL_POST_CAPTION_MAX_LENGTH = 1024;
-export const TELEGRAM_CHANNEL_POST_MEDIA_FILE_NAME_MAX_LENGTH = 255;
+const TELEGRAM_CHANNEL_POST_CAPTION_MAX_LENGTH = 1024;
+const TELEGRAM_CHANNEL_POST_MEDIA_FILE_NAME_MAX_LENGTH = 255;
 
 /** Safe, content-free local validation failure for channel media publication intent. */
 export class TelegramChannelPostValidationError extends Error {
@@ -195,6 +201,7 @@ interface TelegramChannelPostJournalFile {
 
 export interface TelegramChannelPostJournalStoreOptions {
   path: string;
+  runtimeDir?: string;
   profileName: string;
   tokenSha256: string;
   maxRecords?: number;
@@ -329,19 +336,6 @@ export function registerTelegramChannelPostListTool(
   });
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return !!value && typeof value === "object" && !Array.isArray(value);
-}
-
-function hasOnlyKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
-  const allowed = new Set(keys);
-  return Object.keys(value).every(key => allowed.has(key));
-}
-
-function isSafeTime(value: unknown): value is number {
-  return Number.isSafeInteger(value) && (value as number) >= 0;
-}
-
 function normalizeChannel(value: unknown): TelegramChannelPostAddress {
   if (Number.isSafeInteger(value) && (value as number) < 0) return value as number;
   if (typeof value === "string" && /^@[A-Za-z0-9_]{5,32}$/u.test(value)) {
@@ -454,9 +448,24 @@ function validateRecord(value: unknown): TelegramChannelPostRecord {
   throw new TelegramChannelPostJournalError("invalid", "Telegram channel post journal contains an invalid state.");
 }
 
+function parseTelegramChannelPostJournalFile(value: unknown, profileName: string, tokenSha256: string): TelegramChannelPostJournalFile {
+  if (!isRecord(value) || !hasOnlyKeys(value, ["version", "profile", "tokenSha256", "records"]) ||
+      value.version !== CHANNEL_POST_JOURNAL_VERSION || value.profile !== profileName ||
+      value.tokenSha256 !== tokenSha256 || !Array.isArray(value.records)) {
+    throw new TelegramChannelPostJournalError("conflict", "Telegram channel post journal identity or schema does not match.");
+  }
+  const records = value.records.map(validateRecord);
+  if (new Set(records.map(record => record.operationId)).size !== records.length) {
+    throw new TelegramChannelPostJournalError("invalid", "Telegram channel post journal contains duplicate operation IDs.");
+  }
+  return { version: CHANNEL_POST_JOURNAL_VERSION, profile: profileName, tokenSha256, records };
+}
+
 export function createTelegramChannelPostJournalStore(
   options: TelegramChannelPostJournalStoreOptions,
 ): TelegramChannelPostJournalStore {
+  options = { ...options };
+  const publicationPaths = getTelegramJournalPublicationPaths(options.path, options.runtimeDir);
   const maxRecords = options.maxRecords ?? DEFAULT_MAX_RECORDS;
   const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
   const now = options.getNowMs ?? Date.now;
@@ -491,17 +500,7 @@ export function createTelegramChannelPostJournalStore(
         throw new TelegramChannelPostJournalError("conflict", "Telegram channel post journal changed during inspection.");
       }
       const value = JSON.parse(readFileSync(fd, "utf8")) as unknown;
-      if (!isRecord(value) || !hasOnlyKeys(value, ["version", "profile", "tokenSha256", "records"]) ||
-          value.version !== CHANNEL_POST_JOURNAL_VERSION || value.profile !== options.profileName ||
-          value.tokenSha256 !== options.tokenSha256 || !Array.isArray(value.records)) {
-        throw new TelegramChannelPostJournalError("conflict", "Telegram channel post journal identity or schema does not match.");
-      }
-      const records = value.records.map(validateRecord);
-      if (new Set(records.map(record => record.operationId)).size !== records.length) {
-        throw new TelegramChannelPostJournalError("invalid", "Telegram channel post journal contains duplicate operation IDs.");
-      }
-      return { version: CHANNEL_POST_JOURNAL_VERSION, profile: options.profileName,
-        tokenSha256: options.tokenSha256, records };
+      return parseTelegramChannelPostJournalFile(value, options.profileName, options.tokenSha256);
     } catch (error) {
       if (error instanceof TelegramChannelPostJournalError) throw error;
       throw new TelegramChannelPostJournalError("io", "Could not read Telegram channel post journal.", error);
@@ -517,8 +516,9 @@ export function createTelegramChannelPostJournalStore(
     if (Buffer.byteLength(serialized) > maxBytes) {
       throw new TelegramChannelPostJournalError("capacity", "Telegram channel post journal byte limit reached.");
     }
-    const temporaryPath = `${options.path}.${process.pid}.${randomUUID()}.tmp`;
+    const temporaryPath = `${publicationPaths.temporaryBasePath}.${process.pid}.${randomUUID()}.tmp`;
     mkdirSync(dirname(options.path), { recursive: true, mode: 0o700 });
+    mkdirSync(dirname(temporaryPath), { recursive: true, mode: 0o700 });
     try {
       writeFileSync(temporaryPath, serialized, { encoding: "utf8", mode: 0o600 });
       chmodSync(temporaryPath, 0o600);
@@ -532,7 +532,7 @@ export function createTelegramChannelPostJournalStore(
   };
   const mutate = <T>(operation: (file: TelegramChannelPostJournalFile) => T): T => {
     try {
-      return withTelegramFileTransaction(`${options.path}.transaction`, () => operation(read()));
+      return withTelegramFileTransaction(publicationPaths.transactionPath, () => operation(read()));
     } catch (error) {
       if (error instanceof TelegramChannelPostJournalError) throw error;
       throw new TelegramChannelPostJournalError("io", "Telegram channel post journal mutation failed.", error);

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

@@ -121,7 +121,7 @@ function normalizeCommandTemplateDefaults(
   return normalized;
 }
 
-export function resolveInheritedDefaultReferences(
+function resolveInheritedDefaultReferences(
   ownDefaults: Record<string, unknown> | undefined,
   inheritedDefaults: Record<string, unknown> | undefined,
   runtimeValues: Record<string, unknown> = {},
@@ -142,7 +142,7 @@ export function resolveInheritedDefaultReferences(
   return resolved;
 }
 
-export function resolveCommandTemplateRepeat(
+function resolveCommandTemplateRepeat(
   value: number | string | undefined,
   values: Record<string, unknown> = {},
 ): number | undefined {
@@ -367,7 +367,7 @@ function pad(value: number, width: number): string {
   return String(value).padStart(width, "0");
 }
 
-export function getCommandTemplateRepeatDefaults(
+function getCommandTemplateRepeatDefaults(
   index: number,
   repeat: number,
 ): Record<string, string> {
@@ -516,7 +516,7 @@ function parseCommandTemplatePlaceholderContent(
   };
 }
 
-export function getCommandTemplateDefaults(
+function getCommandTemplateDefaults(
   config: CommandTemplateConfig | undefined,
 ): Record<string, string> {
   const normalizedConfig = config
@@ -588,7 +588,7 @@ export function splitCommandTemplate(input: string): string[] {
   return words;
 }
 
-export function expandCommandTemplateExecutable(
+function expandCommandTemplateExecutable(
   command: string,
   cwd: string,
 ): string {

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

@@ -91,11 +91,11 @@ function getOrCreateTelegramCommandRegistry(): TelegramExtensionCommandRegistry
   return registry;
 }
 
-export function normalizeTelegramExtensionCommandName(name: string): string {
+function normalizeTelegramExtensionCommandName(name: string): string {
   return name.trim().replace(/^\/+/, "").toLowerCase();
 }
 
-export function isTelegramExtensionCommandName(name: string): boolean {
+function isTelegramExtensionCommandName(name: string): boolean {
   return TELEGRAM_BOT_COMMAND_NAME_PATTERN.test(name);
 }
 
@@ -144,7 +144,7 @@ export function registerTelegramCommand(
   };
 }
 
-export function getTelegramExtensionCommands(): RegisteredTelegramExtensionCommand[] {
+function getTelegramExtensionCommands(): RegisteredTelegramExtensionCommand[] {
   return Array.from(
     getOrCreateTelegramCommandRegistry().commands.values(),
   ).sort((a, b) => a.order - b.order || a.name.localeCompare(b.name));
@@ -181,7 +181,7 @@ export const TELEGRAM_COMMAND_EMOJI = {
 
 export type TelegramCommandEmojiName = keyof typeof TELEGRAM_COMMAND_EMOJI;
 
-export function getTelegramCommandEmoji(
+function getTelegramCommandEmoji(
   command: TelegramCommandEmojiName,
 ): string {
   return TELEGRAM_COMMAND_EMOJI[command];
@@ -235,12 +235,12 @@ export function formatTelegramAutomaticThreadDisplayNameRestoredHeading(
   return `<b>✅ Automatic Thread display name restored as <i>${escapeHtml(name)}</i>.</b>`;
 }
 
-export const TELEGRAM_COMPACTION_STARTED_TEXT =
+const TELEGRAM_COMPACTION_STARTED_TEXT =
   formatTelegramInformationHeading(
     getTelegramCommandEmoji("compact"),
     "Compaction started.",
   );
-export const TELEGRAM_COMPACTION_COMPLETED_TEXT =
+const TELEGRAM_COMPACTION_COMPLETED_TEXT =
   formatTelegramInformationHeading("✅", "Compaction completed.");
 export const TELEGRAM_COMPACTION_STARTED_MARKDOWN =
   `**${formatTelegramCommandEmojiPrefix("compact")}Compaction started.**`;
@@ -254,7 +254,7 @@ function formatTelegramBotCommandDescription(
   return `${formatTelegramCommandEmojiPrefix(command)}${description}`;
 }
 
-export const TELEGRAM_BUILTIN_BOT_COMMANDS: readonly TelegramBotCommandDefinition[] =
+const TELEGRAM_BUILTIN_BOT_COMMANDS: readonly TelegramBotCommandDefinition[] =
   [
     {
       command: "start",
@@ -1504,7 +1504,7 @@ export async function handleTelegramNextCommand(deps: {
   deps.updateStatus();
 }
 
-export async function handleTelegramContinueCommand<TMessage, TContext>(
+async function handleTelegramContinueCommand<TMessage, TContext>(
   message: TMessage,
   ctx: TContext,
   deps: {
@@ -1530,7 +1530,7 @@ function dispatchNextQueuedTelegramTurnAfterCompact(
   deps.dispatchNextQueuedTelegramTurn();
 }
 
-export function buildTelegramNewConfirmationReplyMarkup(): TelegramCompactConfirmationReplyMarkup {
+function buildTelegramNewConfirmationReplyMarkup(): TelegramCompactConfirmationReplyMarkup {
   return {
     inline_keyboard: [
       [
@@ -1541,7 +1541,7 @@ export function buildTelegramNewConfirmationReplyMarkup(): TelegramCompactConfir
   };
 }
 
-export function getTelegramNewConfirmationHtml(): string {
+function getTelegramNewConfirmationHtml(): string {
   return "<b>Start a new session?</b>";
 }
 
@@ -1588,7 +1588,7 @@ export async function handleTelegramNewConfirmationCallback<TContext>(
   return true;
 }
 
-export function buildTelegramCompactConfirmationReplyMarkup(): TelegramCompactConfirmationReplyMarkup {
+function buildTelegramCompactConfirmationReplyMarkup(): TelegramCompactConfirmationReplyMarkup {
   return {
     inline_keyboard: [
       [
@@ -1599,11 +1599,11 @@ export function buildTelegramCompactConfirmationReplyMarkup(): TelegramCompactCo
   };
 }
 
-export function getTelegramCompactConfirmationHtml(): string {
+function getTelegramCompactConfirmationHtml(): string {
   return "<b>Compact session?</b>";
 }
 
-export async function openTelegramCompactConfirmation(
+async function openTelegramCompactConfirmation(
   target: TelegramCommandMessageTarget,
   deps: TelegramCompactConfirmationDeps,
 ): Promise<void> {
@@ -2373,7 +2373,7 @@ export const TELEGRAM_INTERNAL_COMMAND_DESCRIPTION =
 export const TELEGRAM_INTERNAL_MANUAL_USE_MESSAGE =
   "This internal Telegram command cannot be run manually.";
 
-export function delayTelegramSessionAction(delayMs: number): Promise<void> {
+function delayTelegramSessionAction(delayMs: number): Promise<void> {
   return new Promise<void>((resolve) => setTimeout(resolve, delayMs));
 }
 
@@ -2433,7 +2433,7 @@ export async function settleTelegramSessionReplacement(
   return "stale";
 }
 
-export function createTelegramSessionReplacementSettlementRuntime<TContext>(deps: {
+function createTelegramSessionReplacementSettlementRuntime<TContext>(deps: {
   resolve: (ctx: TContext) => TelegramSessionReplacementSettlementDeps | undefined;
   onResult?: (result: "none" | "settled" | "expired" | "failed" | "stale") => void;
   onError?: (error: unknown) => void;

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

@@ -24,6 +24,7 @@ import {
 export { TELEGRAM_DEFAULT_PROFILE_NAME } from "./paths.ts";
 
 import type { CommandTemplateObjectConfig } from "./command-templates.ts";
+import { isWireRecord as isPlainConfigRecord } from "./wire.ts";
 import type { TelegramInboundHandlerConfig } from "./inbound.ts";
 import { withTelegramFileTransaction } from "./locks.ts";
 
@@ -75,7 +76,7 @@ export type TelegramBotTokenReference =
  * environment-variable references. Any other `$`-prefixed value is malformed
  * rather than a literal secret so a broken reference fails closed.
  */
-export function getTelegramBotTokenReference(
+function getTelegramBotTokenReference(
   value: string | undefined,
 ): TelegramBotTokenReference | undefined {
   const trimmed = value?.trim();
@@ -115,8 +116,6 @@ export function getTelegramBotTokenDiagnostic(
   return `Telegram bot token environment variable ${reference.variable} is not set.`;
 }
 
-export type TelegramOutboundCommandTemplateConfig =
-  string | CommandTemplateObjectConfig;
 export interface TelegramOutboundHandlerConfig extends CommandTemplateObjectConfig {
   type?: string;
   match?: string | string[];
@@ -465,10 +464,6 @@ export async function writeTelegramConfig(
   await chmod(configPath, 0o600);
 }
 
-function isPlainConfigRecord(value: unknown): value is Record<string, unknown> {
-  return !!value && typeof value === "object" && !Array.isArray(value);
-}
-
 function cloneTelegramConfig<T>(value: T): T {
   return structuredClone(value);
 }
@@ -963,7 +958,7 @@ export function createTelegramConfigStore(
   };
 }
 
-export function createTelegramDraftPreviewsChecker(
+function createTelegramDraftPreviewsChecker(
   configStore: Pick<TelegramConfigStore, "get">,
 ): () => boolean {
   return () => {
@@ -977,7 +972,7 @@ export function createTelegramDraftPreviewsChecker(
   };
 }
 
-export function createTelegramDraftPreviewsSetter(
+function createTelegramDraftPreviewsSetter(
   configStore: TelegramMutableConfigStore,
 ): (enabled: boolean) => Promise<void> {
   return async (enabled) => {
@@ -996,7 +991,7 @@ export function createTelegramDraftPreviewsSetter(
   };
 }
 
-export function createTelegramAssistantRenderingModeGetter(
+function createTelegramAssistantRenderingModeGetter(
   configStore: Pick<TelegramConfigStore, "get">,
 ): () => TelegramAssistantRenderingMode {
   return () => {
@@ -1006,7 +1001,7 @@ export function createTelegramAssistantRenderingModeGetter(
   };
 }
 
-export function createTelegramAssistantRenderingModeSetter(
+function createTelegramAssistantRenderingModeSetter(
   configStore: TelegramMutableConfigStore,
 ): (mode: TelegramAssistantRenderingMode) => Promise<void> {
   return async (mode) => {
@@ -1022,7 +1017,7 @@ export function createTelegramAssistantRenderingModeSetter(
   };
 }
 
-export function createTelegramActivityVerbosityGetter(
+function createTelegramActivityVerbosityGetter(
   configStore: Pick<TelegramConfigStore, "get">,
 ): () => TelegramActivityVerbosity {
   return () => {
@@ -1044,13 +1039,13 @@ export function createTelegramActivityVerbosityGetter(
   };
 }
 
-export function createTelegramActivityVerbosityRefresher(
+function createTelegramActivityVerbosityRefresher(
   configStore: TelegramMutableConfigStore,
 ): () => Promise<void> {
   return () => loadLatestTelegramConfig(configStore);
 }
 
-export function createTelegramActivityVerbositySetter(
+function createTelegramActivityVerbositySetter(
   configStore: TelegramMutableConfigStore,
 ): (verbosity: TelegramActivityVerbosity) => Promise<void> {
   return async (verbosity) => {
@@ -1210,13 +1205,13 @@ export function createTelegramProactivePushTargetGetter(deps: {
   };
 }
 
-export function createTelegramAutomaticThreadCleanupChecker(
+function createTelegramAutomaticThreadCleanupChecker(
   configStore: Pick<TelegramConfigStore, "get">,
 ): () => boolean {
   return () => configStore.get().threads?.automaticCleanup ?? true;
 }
 
-export function createTelegramAutomaticThreadCleanupResolver(
+function createTelegramAutomaticThreadCleanupResolver(
   configStore: TelegramMutableConfigStore,
 ): () => Promise<boolean> {
   return async () => {
@@ -1230,7 +1225,7 @@ export function createTelegramAutomaticThreadCleanupResolver(
   };
 }
 
-export function createTelegramAutomaticThreadCleanupSetter(
+function createTelegramAutomaticThreadCleanupSetter(
   configStore: TelegramMutableConfigStore,
 ): (enabled: boolean) => Promise<void> {
   return async (enabled) => {

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

@@ -14,6 +14,7 @@ import {
   renderTelegramMessage,
 } from "./replies.ts";
 import {
+  areTelegramTargetsEqual as areDeliveryTargetsEqual,
   getTelegramTargetThreadParams,
   type TelegramTarget,
 } from "./target.ts";
@@ -262,7 +263,7 @@ function failure<T>(
     : { ok: false, reason, message, partial, ...retry };
 }
 
-export function classifyTelegramDeliveryTransportError(error: unknown): {
+function classifyTelegramDeliveryTransportError(error: unknown): {
   reason: Extract<TelegramDeliveryFailureReason,
     "commit-unknown" | "message-unavailable" | "rate-limited" |
     "transport-retryable" | "transport-failed">;
@@ -374,13 +375,6 @@ export function isTelegramDeliveryExplicitTargetAuthorized(
   });
 }
 
-function areDeliveryTargetsEqual(
-  left: TelegramDeliveryTarget,
-  right: TelegramDeliveryTarget,
-): boolean {
-  return left.chatId === right.chatId && left.threadId === right.threadId;
-}
-
 function cloneTarget(target: TelegramDeliveryTarget): TelegramDeliveryTarget {
   return target.threadId === undefined
     ? { chatId: target.chatId }